In the previous section, we prepared our machine to deploy applications to AppFog. We can now take a look at creating our first application. In this section, you will learn how to deploy applications to AppFog as well as manage your application using the af command-line tool.
AppFog allows anyone to get started and try out running an instance by using some predefined jump-start examples. For our first application, let's use one of these jump-starts. Just log in to the AppFog console, then go to Jump Start and click on the Create App link or on New App.
On the new app page, you can see various jump-starts available. At the jump-start page, select Ruby on Rails and then select Rackspace DFW as the infrastructure. Fill in your application subdomain name and then click on the Create App button.
After a few seconds, you will automatically be brought to the application's details page, where we can see the application's status, infrastructure, runtime, and even the downloaded source code! Your application is now up and running on AppFog. Awesome, right? You can view your live application by clicking on the Visit Live Site button at the top of the page.
You'll be presented with the following screen:
By using the af tool, we can get even more information about the AppFog platform, for example, running af info to display the system and account information.
c:optappfog-starterappfog-blog>af info AppFog Free Your Cloud Edition For support visit http://support.appfog.com Target: https://api.appfog.com (v0.999) Client: v0.3.18.12 User: [email protected] Usage: Memory (384.0M of 2.0G total) Services (1 of 8 total) Apps (1 of 9999 total)
To display a list of supported runtimes for the AppFog platform, run the af runtimes command:
c:optappfog-starterappfog-blog>af runtimes +---------+-------------+---------+ | Name | Description | Version | +---------+-------------+---------+ | java | | 1.7.0 | | php | | 5.3.10 | | ruby18 | | 1.8.7 | | ruby192 | | 1.9.2 | | ruby193 | | 1.9.3 | | python2 | | 2.7.3 | | node04 | | 0.4.12 | | node06 | | 0.6.17 | | node08 | | 0.8.14 | +---------+-------------+---------+
AppFog also provides quite a number of services that developers can use in their applications. To view the entire list of services, you can use the af services command:
c:optappfog-starterappfog-blog>af services ============== System Services ============== +------------+---------+-------------------------------+ | Service | Version | Description | +------------+---------+-------------------------------+ | mongodb | 1.8 | MongoDB NoSQL store | | mysql | 5.1 | MySQL database service | | postgresql | 9.1 | PostgreSQL database service | | rabbitmq | 2.4 | RabbitMQ message queue | | redis | 2.2 | Redis key-value store service | +------------+---------+-------------------------------+
So we know the languages and services that are available, but which frameworks does AppFog support? Well, simply running af frameworks will show you the entire list:
c:optappfog-starterappfog-blog>af frameworks +------------+ | Name | +------------+ | spring | | php | | play | | rails3 | | sinatra | | rack | | django | | lift | | grails | | standalone | | wsgi | | otp_rebar | | java_web | | node | +------------+
The last system information you can get from the af tool is about the different infrastructures available for deployments. Running af infras will print out the complete list:
c:optappfog-starterappfog-blog>af infras +--------+-------------------------+ | Name | Description | +--------+-------------------------+ | aws | AWS US East - Virginia | | eu-aws | AWS EU West - Ireland | | ap-aws | AWS Asia SE - Singapore | | hp | HP AZ 2 - Las Vegas | +--------+-------------------------+
As you can see, af allows you to get a lot of information about the AppFog ecosystem. In the next section, we will take a look at deploying a new app using af.
You have had a taste of deploying to AppFog with the jump-start example, but now let's take a look at deploying a Ruby on Rails app from scratch. To create a new Ruby on Rails application, open the console and run rails new appfog-blog. After that, you need to navigate to the newly created directory using cd appfog-blog. Finally, you can run rails server in the application directory to start the WEBrick server.
c:optappfog-starter>rails new appfog-blog c:optappfog-starter>cd appfog-blog c:optappfog-starterappfog-blog>rails server # or use rails s => Booting WEBrick => Rails 3.2.12 application starting in development on http://0.0.0.0:3000 => Call with -d to detach => Ctrl-C to shutdown server [2013-03-09 11:17:22] INFO WEBrick 1.3.1 [2013-03-09 11:17:22] INFO ruby 1.9.3 (2013-02-06) [i386-mingw32] [2013-03-09 11:17:22] INFO WEBrick::HTTPServer#start: pid=1320 port=3000
You can now open your browser and go to http://localhost:3000 to view the default Rails application. Cool. Let's now deploy this Rails application to AppFog using the af command-line tool.
If you haven't logged in yet, you can do so with the af login command:
c:optappfog-starterappfog-blog>af login Attempting login to [https://api.appfog.com] Email: [email protected] Password: ************** Successfully logged into [https://api.appfog.com]
After successfully logging in, you can deploy to AppFog using af push:
c:optappfog-starterappfog-blog>bundle package c:optappfog-starterappfog-blog>bundle install c:optappfog-starterappfog-blog>bundle exec rake assets:precompile c:optappfog-starterappfog-blog>af push appfog-blog Would you like to deploy from the current directory? [Yn]: y Detected a Rails Application, is this correct? [Yn]: y 1: AWS US East - Virginia 2: AWS EU West - Ireland 3: AWS Asia SE - Singapore4: HP AZ 2 - Las Vegas Select Infrastructure: 4 Application Deployed URL [appfog-blog.hp.af.cm]: Memory reservation (128M, 256M, 512M, 1G, 2G) [256M]: How many instances? [1]: Create services to bind to 'appfog-blog'? [yN]: y 1: mongodb 2: mysql 3: postgresql 4: rabbitmq 5: redis What kind of service?: 3 Specify the name of the service [postgresql-2fa88]: appfog-blog-data Create another? [yN]: n Would you like to save this configuration? [yN]: n Creating Application: OK Creating Service [appfog-blog-data]: OK Binding Service [appfog-blog-data]: OK Uploading Application: Checking for available resources: OK Processing resources: OK Packing application: OK Uploading (7K): OK Push Status: OK Staging Application 'appfog-blog': OK Starting Application 'appfog-blog': OK
I will now go through each of the prompts that come up while pushing the application. The first question will ask you if you want to deploy from the current directory; you can just press Enter because the default is yes (or type y for yes):
Would you like to deploy from the current directory? [Yn]: y
The next step is to define the application type. AppFog should automatically detect a Rails application so you can just hit Enter (or type y for yes):
Detected a Rails Application, is this correct? [Yn]: y
However, under some circumstances you might want to configure it yourself, in which case you will be shown the following prompts to determine whether it's a standalone application or whether it's an application from one of the listed languages and frameworks.
Detected a Standalone Application, is this correct? [Yn]: n 1: Rails 2: Spring 3: Grails 4: Lift 5: JavaWeb 6: Standalone 7: Sinatra 8: Node 9: PHP 10: Erlang/OTP Rebar 11: WSGI 12: Django 13: Rack 14: Play Select Application Type:
The next step is to select the infrastructure you want to deploy your application on. AppFog provides several infrastructures in different locations, so you can pick the one closest to you. In this case, I choose HP AZ at Las Vegas:
1: AWS US East - Virginia 2: AWS EU West - Ireland 3: AWS Asia SE - Singapore 4: HP AZ 2 - Las Vegas Select Infrastructure: 4
Next, you need to provide the URL you want for your application. AppFog will generate one automatically for you based on the infrastructure you choose; you can just hit Enter to use the default:
Application Deployed URL [appfog-blog.hp.af.cm]:
After that, you need to set how much memory you want allocated for your application. AppFog will set a default value based on your application's language and framework. For example, the allocation for a Java Spring application will be higher than a Rails application. For Rails applications, the default allocation is 256 M, so you can just hit Enter to accept it. To specify the memory unit, you can use M for megabyte and G for gigabyte, for example, 2G, 1G, 1024M, 256M, or 64M:
Memory reservation (128M, 256M, 512M, 1G, 2G) [256M]:
The next step is to define the instances to be deployed. You can just press Enter to use the default (1) or specify an integer for more than one instance:
How many instances? [1]:
After that, you need to decide whether you want to bind any service. For our application, we will add a postgresql database. So type y and hit Enter. Then type the number of the service and hit Enter again to add it.
Create services to bind to 'appfog-blog'? [yN]: y 1: mongodb 2: mysql 3: postgresql 4: rabbitmq 5: redis What kind of service?: 3
At the time of writing, AppFog has a total of five services to choose from, and in my list I entered 3 for postgresql.
The final step is to give your service a name. AppFog will generate one for you, but I suggest adding a better one so that you will able to tell which application that database is related to. I named mine appfog-blog-data to indicate that this service is bound to the appfog-blog application.
Specify the name of the service [postgresql-2fa88]: appfog-blog-data Create another? [yN]: n Would you like to save this configuration? [yN]: n Creating Application: OK Creating Service [appfog-blog-data]: OK Binding Service [appfog-blog-data]: OK
As you can see, it will ask you if you would like to bind more services, because in complex applications, you may need different database persistences for different things, but you can just hit Enter (or type n for no) to let it start creating the application. Once the push is successful, you will be able to navigate to the URL given, which in my case is http://appfog-blog.hp.af.cm, but it goes by what you entered in the setup. You can also run af apps in the console to view all of your AppFog applications along with their URLs:
c:optappfog-starterappfog-blog>af apps +-----------+---+--------+----------------------+------------------+----+ |Application| # | Health | URLS | Services | In | +-----------+---+--------+----------------------+------------------+----+ |appfog-blog| 1 |RUNNING | appfog-blog.hp.af.cm | appfog-blog-data | hp | +-----------+---+-------+-----------------------+------------------+----+
From the output of this command, you can see the number of instances, the application's status, the application's URL(s), the infrastructure, and any services bonded to the application. You can, of course, view all this info from the AppFog web console, which will look similar to the following screenshot:
Your service details can be found under the Services tab:
Let's say that after some time your application's blog starts getting very popular, and the load time is getting very slow. In situations like these, it's time to start scaling your application horizontally by adding more instances. This can be easily done in the AppFog web console by just dragging the slider of instances and pressing Save:
You can do this using the af command as well, by running af instances <appname> <num|delta>. The third parameter (num|delta) can be the total number of instances or a relative number such as +1 to add an instance or -1 to remove an instance.
c:optappfog-starterappfog-blog>af instances appfog-blog +1 Scaling Application instances up to 2: OK
After running the command, you can check the updated status by running af apps again.
c:optappfog-starterappfog-blog>af apps +-----------+---+--------+----------------------+------------------+----+ |Application| # | Health | URLS | Services | In | +-----------+---+--------+----------------------+------------------+----+ |appfog-blog| 2 |RUNNING | appfog-blog.hp.af.cm | appfog-blog-data | hp | +-----------+---+-------+-----------------------+------------------+----+
After running the previous command, you should now have two instances running. AppFog has automatically spun up a new instance and added it to the cluster and has taken care of load balancing without you having to do anything at all. Awesome.
Now let's assume that instead of accommodating more requests, you want to add features to your application and you don't have enough memory. In cases like these, you need to scale your application vertically and add more memory. This can be done through the AppFog web console again by simply dragging the memory slider and pressing the Update button. Note that the application will need to restart to apply the changes, so you should keep this in mind in a production environment.
If you prefer using the command line, you can use the af mem <appname> [memsize] command to scale as well.
c:optappfog-starterappfog-blog>af mem appfog-blog 512MB Updating Memory Reservation to 512M: OK Stopping Application 'appfog-blog': OK Staging Application 'appfog-blog': OK Starting Application 'appfog-blog': .
Note that the af command-line tool recognizes both 512 MB and 512 M. After running the command, you can run af stats again to view the changes.
c:optappfog-starterappfog-blog>af stats appfog-blog +----------+-------------+----------------+--------------+--------------+ | Instance | CPU (Cores) | Memory (limit) | Disk (limit) | Uptime | +----------+-------------+----------------+--------------+--------------+ | 0 | 0.9% (2) | 48.6M (512M) | 0B (1G) | 0d:0h:5m:14s | | 1 | 1.2% (2) | 48.7M (512M) | 0B (1G) | 0d:0h:3m:21s | +----------+-------------+----------------+--------------+--------------+
You have now successfully scaled your application by adding more memory to each instance within seconds, and you didn't need to configure anything.
AppFog provides several services you can bind to your application. These services range from databases such as MySQL, PostgreSQL, and MongoDB to things such as RabbitMQ, a message queue. You can bind more than one service to a single application. To do this, from the web console, go to the Service tab of the AppFog web console, click on the service you want to add, enter a name, and click on the Create button:
You can create a service from the command line using the af tool as well as the af create-service <service> <name> <app> command, where <service> is the type of the service, <name> is the name you want to give the new service, and <app> is the application's name that the service will bind to. To get a list of all the service types, just run the af services command:
c:optappfog-starterappfog-blog>af services ============== System Services ============== +------------+---------+-------------------------------+ | Service | Version | Description | +------------+---------+-------------------------------+ | mongodb | 1.8 | MongoDB NoSQL store | | mysql | 5.1 | MySQL database service | | postgresql | 9.1 | PostgreSQL database service | | rabbitmq | 2.4 | RabbitMQ message queue | | redis | 2.2 | Redis key-value store service | +------------+---------+-------------------------------+
You can create and bind a new service to your application using the following command:
c:optappfog-starterappfog-blog>af create-service mongodb myblog-mongodb appfog-blog 1: AWS US East - Virginia 2: AWS EU West - Ireland 3: AWS Asia SE - Singapore 4: HP AZ 2 - Las Vegas Select Infrastructure: 4 Creating Service: OK Binding Service [myblog-mongodb]: ok
The default URL for your application is a subdomain of *.af.cm, but most of the time you will want to use your own domain, such as myblog.com. There are two types of domains you can attach: the first is a subdomain such as www.myblog.com or blog.mysite.com, and the second is a root domain such as myblog.com or mysite.com. Both these types of domains can be set up with AppFog out of the box.
To map a www subdomain to AppFog, you will need to create a CNAME alias to point the domain to AppFog. The CNAME record is used to specify an alias between one domain and another. Based on the infrastructure of your application, you will need to map to different CNAME hosts provided by AppFog.
|
Infrastructure |
CNAME host |
|---|---|
|
AWS US East |
|
|
AWS Europe West |
|
|
AWS Asia Southeast |
|
|
HP Openstack AZ 2 |
|
Using your domain provider, you can point your domain to AppFog based on the preceding CNAME host. The following screenshot shows an example of using custom domains. This is then mapped by the subdomain to the AppFog AWS Asia Southeast infrastructure. The first entry is used to redirect the root domain from http://myblog.com to the http://www.myblog.com subdomain, and the second entry is used to alias the www subdomain to AppFog's CNAME host.
If you want to use a root domain for your application, another option is to create a record to point your root domain to AppFog. A record is used to map a host name to an IP.
|
Infrastructure |
CNAME host |
|---|---|
|
AWS US East |
|
|
AWS Europe West |
|
|
AWS Asia Southeast |
|
|
HP Openstack AZ 2* |
|
* Beta, subject to change
In this second example, we are doing the opposite; we are redirecting the subdomain to the root domain and mapping the root domain directly to AppFog. The first entry with the @ symbol is used to map the root domain to AppFog using a record, and the second entry is used to redirect the www subdomain to the root domain. This is required so that when a visitor types in http://www.myblog.com, it will redirect him/her to http://myblog.com.
Sometimes, having too much to choose from gives problems to developers as they might not know which one is better. For a custom domain, it is recommended to use subdomain mapping. This is because subdomain mapping is a map to another CNAME host. If the underlying IP for the CNAME host is changed, it does not have any impact on your application. When we use a root domain, the mapping is done using IP addresses. If the IP is changed, you need to manually change the mapping to a new IP; this will cause your application to go down while waiting for the DNS to be propagated.
Once you have configured the DNS for mapping domains to AppFog, you need to tell AppFog the application it belongs to. To do this, from the AppFog web console, go to the Domain Names tab, enter the naked domain or www subdomain you mapped, and hit the Update button.
You can also easily remove the mapped domain by removing the entry, which is done by clicking on the Remove button and then on the Update button. You can also add a domain from the command-line tool by running the af map <appname> <url> command:
c:optappfog-starterappfog-blog>af map appfog-blog www.myblog.com Successfully mapped url
Once you add the domain URL, you can browse to it and your application will show up.
You can also remove/unmap the domains with the af unmap <appname> <url> command:
c:optappfog-starterappfog-blog>af unmap appfog-blog www.myblog.com Successfully unmapped url
AppFog allows you to create custom environment variables for use in production. This is very helpful to define environment-specific values such as the database URL, the database username, and the database password. The environment variable configuration page can be found under the Env Variables tab on the application detail page.
The af tool offers the same functionalities for you to manage environment variables. You can use af env <appname> to list all of the environment variables of the specific application.
c:optappfog-starterappfog-blog>af env appfog-blog +----------------+--------------+ | Variable | Value | +----------------+--------------+ | ADMIN_USERNAME | dreamandme | | ADMIN_PASSWORD | ThisIsSecret | +----------------+--------------+
Similarly, you can add and remove environment variables using af env-add <appname> <variable[=]value> and af env-del <appname> <variable> respectively. For example, to remove the ADMIN_USERNAME environment variable, you can run af env-del appfog-blog ADMIN_USERNAME.
c:optappfog-starterappfog-blog>af env-del appfog-blog ADMIN_USERNAME Deleting Environment Variable [ADMIN_USERNAME]: OK Stopping Application 'appfog-blog': OK Staging Application 'appfog-blog': OK Starting Application 'appfog-blog': OK
In this section, you have learned how to deploy both AppFog's jump-start to create a new application within minutes and deploy to one of the infrastructures as well as the custom application we created from scratch. We also covered the af tool in detail and learned how to do things such as add services, horizontal and vertical scaling, and custom domain mapping.