PaaS Deployment

Overview

You can deploy your Codenvy-built application to nearly any PaaS. There are three ways this is done – each with its own strengths:

  • Easy: Using our built-in deployment menu (available for Google App Engine)
  • Hands-off: Automatically triggered by your version control system (available for Heroku and OpenShift)
  • Powerful: Adding the PaaS’ Deployment SDK to your Docker image for complete control (Pivotal, AppFog)

Google App Engine Deployment

Codenvy provides integration with Google App Engine (GAE) which makes it possible to deploy and update apps in GAE and run a local devserver to preview applications on Codenvy runners before deploying them. The plugin uses the GAE SDK (version 1.9.14) for Java, Python and PHP.

Creating a GAE Application with the Project Wizard

You can create an application pre-configured to use GAE as its deployment target from scratch in the Project Wizard. There are three project types available:

  1. JAVA GAE
  2. Python GAE
  3. PHP GAE

Java GAE

When creating a Java GAE project with the Project Wizard, we’ll generate an empty project with the right folder structure and some mandatory files:

  • pom.xml
  • web.xml
  • appengine-web.xml

In the first page of the Project Wizard, you will be prompted to enter basic project configuration information: artifact and group ID for Maven; application ID for Google App Engine. Note that if you do not have an application on GAE or you are unsure of what your app ID is, enter a dummy name, and change it in the appengine-web.xml file when you double check it on GAE or create a new app.

The last page of the Project Wizard is used to setup the runtime environment. For Java select:
» java > web > gae1914

This environment will launch your code in the Jetty appserver preconfigured to deploy to GAE. It uses the dev_appserver command.

Python GAE

We create a simple project with a Hello World example and an app.yaml file for GAE deployment. In the first page of the Project Wizard, you will be prompted to enter the Application ID for Google App Engine. Note that if you do not have an application on GAE or you are unsure of what your app ID is, enter a dummy name, and change it in the app.yaml file once you find it.

The last page of the Project Wizard is used to setup the runtime environment. For Python you have two options:

  1. » python > web > python27_gae1914 for a pure Python GAE app that uses native Python libs specified in app.yaml file.
  2. » python > web > python27_gae1914_ext_lib should be chosen if your Python GAE application uses 3rd party libs, specified in requirements.txt. The Docker image will fail if you don’t have this file in your project, since it adds the file before running the app and performs pip install.
  3. In these ‘local’ runtime environments dev_appserver command is used.

    PHP GAE

    We create a simple project with a Hello World example and an app.yaml file for GAE deployment. In the first page of the Project Wizard, you will be prompted to enter the Application ID for Google App Engine. Note that if you do not have an application on GAE or you are unsure of what your app ID is, enter a dummy name, and change it in the app.yaml file once you find it.

    The last page of the Project Wizard is used to setup the runtime environment. For PHP select:
    » php > web > php56_gae1914

    In this ‘local’ runtime environment dev_appserver command is used.

    Import a GAE Application

    You may import an existing GAE application from VCS or as a remotely hosted ZIP. It is not possible today to import an application directly from GAE. The Project Wizard will help you import your GAE app – you can start the wizard using the “Import” button in the Codenvy User Dashboard, or by selecting File > Import > Import From Location in the Codenvy cloud IDE menu.

    Configure a GAE Application: Project Type

    You will need to choose a project type for your GAE app. Choose between Java, Python or PHP. Make sure you select one of the GAE project types outlined in the “Creating a GAE Application with the Project Wizard” section above. Built-in deployment to GAE will be grayed out in the UI if a standard Java, Python or PHP project type is chosen.

    Configure GAE Application: Settings

    The next page of the wizard will ask you to configure your GAE app. If this is a Java application you can change group and artifact IDs, and application ID in appengine-web.xml. For Python and PHP you can change only application ID in the app.yaml configuration file. If you are cloning someone else’s application, it will likely include someone else’s application ID or a dummy application ID. Change this to your own application ID to allow the project to deploy.

    Configure GAE Application: Runtime

    See available runtime descriptions in the Java, Python and PHP sub-sections of “Creating a GAE Application with the Project Wizard” above.

    Configure an Existing Project to Use GAE

    If you have an existing project in your workspace, you can convert it to GAE project. Start by opening the application you want to enable GAE deployment for in the Codenvy IDE. Once open, choose “File > Project Configuration” from the menu then follow the instructions listed in the “Creating a GAE Application with the Project Wizard” section above.

    Configuration Notes

    For GAE projects there are certain files required that your project must have for deployment to be successful. For Java projects, it needs to have a correct src/main/webapp/appengine-web.xml file. You can read this article on Google’s site to learn how to define this file. For Python or PHP projects, an app.yaml configuration file is required. You can read about defining this file for Python and GAE, or PHP and GAE on Google’s site. Without these files a project cannot be deployed to GAE and run in Codenvy runners.

    If those files are missing or are incorrect you will see error messages in Codenvy Event console.

    Deploy a GAE-Enabled Application

    Having successfully configured a GAE application, you are ready to deploy it. If everything is OK you should see an active Deploy menu in your workspace. Click Google App Engine. You will be asked to authenticate with your the Google Account where your application exists.

    Upon successful Google authentication, you can deploy your application. There are several scenarios:

    Successful Deploy

    Your app has been successfully deploy to GAE. This means you have the correct application ID and settings in a configuration file (either app.yaml or appengine-web.xml), and application build was successful as well (relevant for Maven projects only).

    Failure to Deploy: Config Issues

    If you use a non-existent application ID you will see an error message explaining the nature of this problem. There are two solutions: either edit the GAE configuration file to make sure it has the right app ID or create a new application on GAE. If you choose the latter, you will be redirected to GAE page where can create a new app. Once the app is created, you are taken back to your workspace, and the application ID (the one you have created) is automatically inserted into GAE config file.

    Failure to Deploy: Build Failure

    When you deploy a Java GAE application, it is first built on a builder instance, and then build artifact is sent to GAE. If the build fails, deploy will fail automatically. If application build fails, check Maven logs to fix the build.

    Common Errors

    Errors in GAE Config

    Every GAE project has a config file, either appengine-web.xml or app.yaml with a set of parameters. You may want to look through Google documentation on configuring Java, Python and PHP GAE projects. There are mandatory elements and optional ones. So, if there are any errors or inconsistencies in these elements, the deployment will fail with a GAE SDK error message.

    When creating a GAE project from scratch, we use a minimum set of mandatory configuration elements to simplify things. However, if you import somebody else’s application, review its configuration file to make sure there are no errors and inconsistencies.

    Using Paid Features

    It may happen that the application fails to deploy because it attempts to use configuration parameters available only to applications with billing enabled. A typical example is using virtual machine settings for Java projects.

    Authenticating With a Wrong Google Account

    If you have several Google accounts, make sure you authenticate with the account where application with a specified ID exists. Check your Google Cloud Console for details.

    Datastore Indexes

    Your application may use a datastore. In this case, your project should have a dedicated datastore configuration file: datastore-indexes.xml for Java and index.yaml for Python and PHP. If the application needs this file, but it’s missing in the project, the deployment will succeed, but you will get Server 500 error if you follow GAE application URL. Check your GAE logs for indications of this problem.

    If you have a datastore configuration file, and deployment was successful but you still can’t see your app up and running on GAE, be patient, since it takes some time for datastore indexes to build. You may want to log in to GAE console to check status of Datastore Indexes. If there have status building, everything is OK and in a minute or so this status will be replaced with serving. After this happens, your application is up and running.

    Grayed Out Deploy Menu

    If the Deploy menu item in Codenvy is grayed out check your project configuration (“File > Project Configuration”) to ensure that it is using one of the GAE-enabled environments outlined in the “Creating a GAE Application with the Project Wizard” at the top of these docs.

    Non-Existing Libs

    If you get this error check the libraries declared either in app.yaml or requirements.txt are up-to-date and downloadable. Checking the GAE logs will highlight this as well.

    Push to Deploy

    There is no direct integration with the Push-to-Deploy feature offer in Google Cloud. However, it is possible to connect a 3rd party repository to your GAE application. Check out the Google documentation related to this feature for more information.

    Once you set up an external repository, GitHub for example, it is then possible to add this repository as a Git remote to your GAE Codenvy project at Git > Remotes. Then, add changes to index, commit them and push to the GitHub repository. As soon as changes are pushed, a webhook triggers a code update on GAE.

    This feature is available for Python and PHP without billing enabled. Java projects require billing enabled for push-to-deploy.

    push2deploy

    AppFog Deployment

    AppFog offers a CLI client to manage apps and account. The CLI is installed as a Ruby gem, so you will need an environment with Ruby:

    
    FROM codenvy/ruby210
    RUN sudo apt-get -y install rubygems
    RUN sudo gem install af
    ADD $app$ /home/user/$app$
    RUN sudo chown -R user:user /home/user
    CMD while true;do true; done
    

    Go to a Terminal, login to your AppFog account, and create/update your applications using AppFog CLI commands. To update an application execute:

    $ af update <appname> [--path]
    

    See: AppFog CLI Commands Reference.

    Similar to Google App Engine, you can build own image with AppFog CLI, upload it to Docker Index and use it as a base image in your custom Dockerfile.

    OpenShift Deployment

    OpenShift relies on a classic Git workflow – git add – git commit – git push. Codenvy supports Git, therefore you can import OpenShift applications, edit them in Codenvy and push changes back to OpenShift.

    Before you proceed with importing OpenShift apps, you should establish secure SSH connection between your Codenvy workspace and OpenShift account.

    Establish SSH Connection

    • in your Codenvy workspace, go to Windows > Preference > SSH Keystore > Generate Key
    • enter hostname rhcloud.com (Important! Just hostname, without www or https://)
    • copy the key
    • go to your OpenShift account settings, and add a new key

    Alternatively, you can upload an existing key in the same menu box.

    Import a Project

    Once done, you can import your OpenShift project into Codenvy either from a Dashboard or from within the workspace at File > Import > Import From Location > GIT. Enter paste ssh Git URL of your OpenShift project. You may see an error signaling about an invalid SSH URL. Odds are that such an error is caused by a slash, for example, ssh://546a110ce0b8cdf8bc000013@openshift1298-newapplic.rhcloud.com/~/git/openshift1298.git/. Just remove ‘/’ and this should fix the problem.

    Push Changes

    Having edited the application, you can push changes back to OpenShift. Add changes to index (Git > Add to Index), commit them (Git > Commit) and push (Git > Remotes > Push). If this is a Java project, the update will take some time, since your push will trigger new project build on the OpenShift side.

    When editing your Maven project, make sure you do not delete your OpenShift profile from pom.xml:

    <profiles>
      <profile>
       <id>openshift</id>
        <build>
         <finalName>yourAppNameHere</finalName>
        </build>
      </profile>
    </profiles> 
    

    CloudFoundry Deployment

    You can deploy your application to CF using Cloud Foundry CLI tool. Here’s a custom Dockerfile example that you can use:

    FROM codenvy/jdk7
    RUN mkdir /home/user/cf
    WORKDIR /home/user/cf
    RUN wget -q http://go-cli.s3-website-us-east-1.amazonaws.com/releases/v6.7.0/cf-cli_amd64.deb && \
        sudo dpkg -i cf-cli_amd64.deb
    

    This will install CF CLI that will let you upload your application to Cloud Foundry. Login to your Pivotal account:

    cf login -a api.run.pivotal.io
    

    There are several ways to proceed. You can either perform builds in the runtime (provide build commands directly in the Dockerfile or navigate to Terminal tab and do it there) or, if it is a Maven or Ant project, perform build with a native builder (for these project types build is kicked off automatically upon hitting Run button) and inject build artifact into the image.

    If the build is performed in the runtime, you need to navigate to application folder and run:

    
    $ cf push <app-name> -n <unique_desired_url>
    

    If the build has been performed with a native builder and you injected build artifact into the image (war or jar), you will need to provide a path to the build artifact:

    $ cf push <app-name> -n <unique_desired_url> -p /home/user/myapp.war
    

    Heroku Deployment

    Heroku uses Git, so deploying to this PaaS is all about adding changes to index, commit them and push to Heroku. All you need to do is to make sure you have generated SSH key and saved it to your Heroku account.

    SSH Connection

    In your Codenvy workspace, go to Window > Preferences > SSH Keystore and generate a new key for Heroku. Enter hostname as heroku.com (no www or https). Once generated, view this key, copy it and manually save to your Heroku account (https://dashboard.heroku.com/account).

    Import Existing Application

    Go to your application settings and copy its Git URL. In your Codenvy workspace, go to File > Import from Location, paste the application URL and import the app. If the SSH key has been accurately generated and saved to your account, there shouldn’t be any issues with this step.

    Update Heroku Application

    Edit your application, add changes to index at Git > Add to Index, commit changes at Git > Commit and push to Heroku at Git > Remotes > Push.

    Having imported a project, all project Git history and settings is saved, so there is no need to add Heroku as Git remote – it is already there.

    Create Heroku Application

    There’s no plugin in Codenvy that integrates with your Heroku account, manages keys and applications. However, it is possible to create a custom runtime with Heroku toolbelt installed, and run native Heroku commands there.

    Here’s a Dockerfile that will build the right environment:

    
    # start with a Codenvy image
    FROM codenvy/shellinabox
    RUN sudo apt-get update && \
        sudo apt-get -y install ruby-full git
    RUN wget -qO- https://toolbelt.heroku.com/install-ubuntu.sh | sh
    
    ADD $app_src$ /home/user/app/
    RUN sudo chown user:user -R /home/user/app
      	 
    # Configure git, initialize repo, add to index and commit
    WORKDIR /home/user/app
    RUN sudo git config --global user.email "example@codenvy.com" && \
        sudo git config --global user.name "John Jameson" && \
        sudo git init && \
        sudo git add . && \
        sudo git commit -m "update from Codenvy"
    CMD sleep 356d
    

    This will build the right environment. Go to Terminal tab to execute a few Heroku and Git commands. When in the terminal, run:

    $ cd app
    $ sudo heroku login
    $ sudo heroku create --http-git
    $ sudo git push heroku master
    

    In simple words, you need to login to your Heroku account, create a new app (this will add https remote ‘heroku’) and push to a remote.