IBM BlueMix

BlueMix offers developers a very flexible platform to deploy your <form.io> applications. The following sections will talk through how to not only deploy an application within BlueMix, but also how to spin up a Docker Deployment of the Form.io infrastructure so that you control all of your data.

Application Deployment

In order to deploy your application within BlueMix, you will be utilizing the Node.js integrations available within that platform. This tutorial also assumes that you already have an application running locally either using one of our predefined templates or an application that already has a build routine to create a serverless application.

To start, you will first need to go and create a new IBM Bluemix account. Once you have established your account, the first thing you will do is to create a new Organization.

You will now name your space, for now we can just use dev*.

Then read the Summary, and press I’m Ready.

Once you are within the main page, the first tasks is to create a new application. We can do this by first clicking on the Compute section.

You will then create a new application.

From here you will click on the Node.js, then click on Continue

Now give your application a name and press Finish

Once the application is done building, you will then want to click on the Overview tab, and then ADD GIT button.

You will then need to give your repo an alias and then click the button that says Create. Then follow the on-screen instructions until it creates a new GIT repository for your application.

BlueMix will automatically create a new repository for you, which we will add our Form.io application to. To get started you will first need to ensure you have GIT installed on your local machine. You can go to https://git-scm.com/ to download and install GIT on your machine. Once you have that installed, you can clone your repo by copying the following URL within BlueMix.

You can now clone this application within your local computer by typing the following, but replacing the URL with your own GIT url.

git clone https://hub.jazz.net/git/formio/formio

You will be required to login to your BlueMix account to download this locally, but this is normal.

Once you have the project downloaded into your own local machine, you will now need to merge the code found within your Form.io application with the code that was provided by default from BlueMix. For example, lets suppose we wish to bootstrap the Todo Application found @ https://github.com/formio/formio-app-todo into BlueMix. We can first Boostrap the project within Form.io by typing the following commands.

npm install -g formio-cli
formio bootstrap formio/formio-app-todo

This will bootstrap a new Todo application within your Form.io account. To merge the BlueMix project with this one, it will be easier to copy the BlueMix deployment pieces into this application, starting with the app.js and manifest.yml files.

You will now need to copy the package.json dependencies of the BlueMix application into the Form.io application.

The resulting package.json file will look something like this when you are done with this task…

Next, you will need to open up the app.js file that you copied over from the BlueMix application and change the following line to include the /dist folder instead of the /public folder.

// serve the files out of ./dist as our main files
app.use(express.static(__dirname + '/dist'));

You are now ready to build your application. Type the following within your terminal within the directory of the Form.io application.

npm install
bower install
gulp build

Just to ensure that your application will run, type the following to test it locally.

gulp serve

You will now need to add your new application on top of the BlueMix application within GIT. The easiest way to do this is to copy the .git folder within BlueMix application and place that within your Form.io application folder. Some computers will hide that folder within the finder window, so you may need to move it manually using terminal (NOTE: the directories will be different for your computer).

mv ~/Documents/formio/bluemix/formio/.git ./

Now within the Form.io application folder, you can commit the application on top of the BlueMix GIT repo by doing the following.

git add -A
git commit -m "Deploy Form.io Serverless App"

And now push that up to BlueMix.

git push origin master

Once you do that you can now go back to your BlueMix interface and restart your application.

Your application should now startup and will be running within BlueMix!

Docker Deployment

By default, your application will be running with all API traffic directed toward the https://form.io domain. In many cases, you may want to have your application submit the forms and data to your own backend with your own database. It is this reason we provide a robust On-premise/Private Cloud deployment using a very well known technology called Docker. This technology allows you to spin up the Form.io infrastructure within your own backend and point all the forms and data to that deployment. IBM BlueMix offers a great solution for Docker deployments, which is what we will cover in this next section.

DNS Configuration

Before you begin, you will need to dedicate a few sub-domains to the Form.io platform. You will need to point these sub-domains to BlueMix. To do this, you will need to create two separate A records which are as follows.

Hostname Description Type Value
api The API subdomain A 75.126.81.68
formio The core Form.io project A 75.126.81.68
<project subdomain> Replace <project subdomain> with the subdomain name of your project within Form.io A 75.126.81.68

Once you have your domain name established, you will now need to add that domain to your BlueMix account. You can do this within the Account » Manage Organizations » Domains section of BlueMix. Once you add the domain, you are now ready to register the Docker container.

Docker Container Registration

The first thing you will do to get started is to log into your BlueMix account and click on Start Container within your dashboard, and then on the next page click Add your own

Next, you will provide a name for your docker image within the BlueMix environement.

To get started, you will need to download both Docker as well as the Cloud Foundry CLI. The best way to get everything setup is to walk through the instructions provided @ https://console.ng.bluemix.net/docs/containers/container_cli_cfic.html

cf login
cf ic init

Next you will pull in the Form.io Docker Image (NOTE: You must have a Commercial License to pull in the Form.io Docker image), then tag it, and then push it to your Private BlueHost account.

docker pull formio/formio-server
docker tag formio/formio-server registry.ng.bluemix.net/[YOUR NAMESPACE]/formio-server
docker push registry.ng.bluemix.net/[YOUR NAMESPACE]/formio-server

Your docker image is ready to deploy, but we will now need to setup the MongoDB database first.

Adding MongoDB

In order to get started, we will first need to create the databases within IBM BlueMix which we will use to store all of the form data. IBM has a service called Compose which they use as their means for deploying these databases.

Once you have an account, you will first want to create a new MongoDB Instance. Once you are done with that, you will need to create a new database.

You will then provide a name for your new database, then press Run.

Next, you will want to add some new users for this database.

You are now ready to deploy your container within BlueMix.

Deploying Docker Container in BlueMix

After you have pushed your Docker image to BlueMix and setup your databases, you will now want to create a single container to startup the Form.io Server. IMPORTANT NOTE: If this is the first deployment you are making, then you will need to make sure you only spin up a single container to start. This is because the database for Form.io is created on the initialization process of the container. If you tried to spin up multiple containers, like you would if you did a Container Group, then that could cause database locking issues.

Within your BlueMix account, click on Start Containers

You should now see your docker container available to launch within BlueMix.

Within the Single Container section, you will now provide the following information.

Now you will click on Advanced Settings and provide the following ENVIRONMENT VARIABLES.

Now, press the CREATE button to create your deployment.

Ensure your container is working

In order to make sure that your container is working well, you can use the IBM Container CLI to get some insight into how it is running. You can use the following command to see a list of options.

cf ic --help

This command is actually a proxy to the Docker CLI so many of the commands that are available within the Docker CLI are also available within the cf ic command. For example, to see a list of running containers, you can use the following command.

cf ic ps

Which will output something like the following.

Using the Container ID provided, you can then view the output from that container to ensure that it booted successfully.

cf ic logs b4ce91c6-f7a

If everything is running smoothly, it should look like the following.

You now have a running Docker image! The next step is to delete this container (we just created it to initialize the database), and now create a Container Group which will allow us to map some Routes from our DNS into the container group. They will also provide some auto scaling capabilities which we would like to take advantage of.

Creating an autoscaling Container Group

BlueMix also has the ability to create an auto scaling container group, which will scale up your servers as the requests to the server increases. It does this through the use of a Container Group. After you have successfully initialized a single container, you can now spin up a Container Group by clicking on Containers as you did in the previous example, but instead of clicking on Single Container, you will click on Scalable Group and provide the following information.

You will then provide the same Environment variables you did in the previous single container deployment.

After this, you will now need to add multiple domains that will redirect to this container. After you launch the first container group, the existing hostname is api. We can assign a new one by using the following command.

cf ic route map -n formio -d <domain> formio-server

After you do that, you will now need to navigate to your Container group within BlueMix. You should now see an edit button.

You can now assign the domain name of the project you are going to create by adding it to the list of routes and pressing save.

You should now be able to use the Environment Switcher within Form.io to manage your project!