Jekyll on Bluemix for New Users

Static sites should be really easy to set up – once you have the HTML, just put the files in a publicly accessible web directory and that should be it. But, one of the things that I wanted to do was to host this on IBM Bluemix and that meant trying to understand a few more things.

This post includes the steps that I had to go through to set it up, and hopefully helps someone who is facing the same issues in getting started. The post is more focused on the Bluemix side of things rather than Jekyll – that will come in a separate post. Just a note that these instructions are for Windows, but the concepts will likely work for any platform.

Overview

As you will find online in articles on different websites we basically need to use the Cloudfoundry Staticfile Buildpack for deploying a static website, i.e., a website that includes no server side business logic/ dynamic pages. The steps seem simple especially as pointed out in the first article I linked above but a few things were not clear to me since I was also using Bluemix for the first time.

So, anyway, that’s what we want to do – set things up to the point that we can deploy a site generated by Jekyll to an instance running on Bluemix so that it is publicly accessible in the browser.

Sign up for Bluemix

If you haven’t already done so, please sign up for Bluemix. You will need a (free) IBM ID for it and then you’ll need to sign up for Bluemix. It’s not complicated, but you need to know the following things for the next few steps:

Your Bluemix Account/ IBM ID (email)
Your Bluemix/ IBM ID Password
Your organization – when creating the account, you would have been asked to create your first organization name
Region – when you create your account, you would have been asked to place the organization in a zone (US, EU or Sydney)
Space – when you create your account, you would have been asked to create a space (e.g., dev, test, etc.)

Bluemix tools – what do I need?

There’s a little bit of confusion when doing this for the first time, so let’s make it really simple. You need only two things:

The Cloudfoundry Command-line tools (called the CF CLI)
The Bluemix Command-line tools (Bluemix CLI)

The links to download both of these are on the Bluemix CLI & Tools pages – the links to the documentation are also on that page, but you don’t need to get into too much detail yet.

Install the CF tools first and then the IBM Bluemix tools. The IBM tools will probably ask you to restart your computer to complete the installation.

Once done, start a command window and type cf – you should see some text scrolling by to indicate that the command ran. Then, type bluemix – if you see some text running by, that’s great, you’re set! In my case, it appears that the Bluemix tools did not update the path. So, you need to add "c:\Program Files\IBM\Bluemix\bin" to your path (assuming you did a default installation) permanently (for your user/ computer) or temporarily (by doing PATH="c:\Program Files\IBM\Bluemix\bin";%PATH% in the command window. After that, when you type in bluemix, it will appear to run – we’re set now!

Elementary Test

The elementary test is to log in to your Bluemix account with your credentials. The simple thing is to just type bluemix login in the command window. It will ask you for your email and password.

E:\blog>bluemix login
Invoking 'cf login'...

API endpoint: https://api.ng.bluemix.net

Email> youremail@somewhere.net

With the correct credentials, it will log in. You will see something like this:

Authenticating...
OK

API endpoint:   https://api.ng.bluemix.net (API version: 2.54.0)
User:           youremail@somewhere.net
No org or space targeted, use 'cf target -o ORG -s SPACE'

If you see the last line showing No org or space... it means that Bluemix is unable to find your organization even though it was able to log you in.

The problem is discussed online and basically comes down to the fact that your account is in some other region but the API endpoint that you are logging in to is the default US zone. So, Bluemix is unable to find your organization in that region and throws up that note. Till you fix it, you can’t get anything done.

Fixing the API Endpoint

This is really simple once you know what you are trying to do:

Find the API endpoint
Run bluemix api to set the endpoint

Since no-one reads the document till something else points to it, take a look at the “Bluemix Intro:”https://www.ng.bluemix.net/docs/overview/index.html#ov_intro to get the endpoints for the URLs but as shown in the article linked above, the details are as below (extracted from the Bluemix site):

Region	Location	Prefix	CF Endpoint	UI Console
US South region	Dallas, US	ng	api.ng.bluemix.net	console.ng.bluemix.net
United Kingdom region	London, England	eu-gb	api.eu-gb.bluemix.net	console.eu-gb.bluemix.net
Sydney region	Sydney, Australia	au-syd	api.au-syd.bluemix.net	console.au-syd.bluemix.net

Note the prefix – it comes in handy at different places.

Just do a bluemix api or cf api to set the API endpoint – in my case, I set it to Sydney since that’s where my organization is set to.

E:\blog>bluemix api https://api.au-syd.bluemix.net
Invoking 'cf api https://api.au-syd.bluemix.net'...

Setting api endpoint to https://api.au-syd.bluemix.net...
OK

API endpoint:   https://api.au-syd.bluemix.net
API version:    2.54.0

If needed, do a bluemix login or cf login at this point. You will see something like this:

E:\projects\blog\jekyll\onghu-uno>cf login
API endpoint: https://api.au-syd.bluemix.net

Email> youremail@somewhere.net

Password>
Authenticating...
OK

Targeted org YOUR_ORGANIZATION

Targeted space YOUR_SPACE

API endpoint:   https://api.au-syd.bluemix.net (API version: 2.54.0)
User:           youremail@somewhere.net
Org:            YOUR_ORGANIZATION
Space:          YOUR_SPACE

Getting your Site Online

Now that you’re able to log in to the site, you’re ready to start to push the site up. I’m assuming that you’re familiar with Jekyll and will know what to do to build your site into the _site folder, depending on how things are set up.

The thing that people will normally point you to is that you need to set up the details in manifest.yml and do a cf push to get done. There are details for this online and we roughly follow this – the only thing that took me some time was trying to figure out how to get started with creating the first application on Bluemix and where to find the hostname to plug in to the YAML file.

Let’s start by planning this out a bit (make some assumptions so that we have a few names we can use in the examples below)

Let’s call this “application” the xyz-123-blog – this is our static website project
We need a sub-domain (or host) on which the site will be available. All public sites on bluemix will end up with a subdomain on the main Bluemix URL (e.g. something.eu-gb.bluemix.net or something.au-syd.bluemix.net) – let’s say that you want it to be xyz-123-production.[REGION].bluemix.net – so, this route or host is xyz-123-production

Other things that we need to set up:

We know that we are using staticfile buildpack for our site.
For most use cases, a small amount of memory will probably be fine for us (e.g. 64M or 128M).
We need to point to where Jekyll will generate the output for our site

So, there are two questions to answer:

Where does manifest.yml go? You can place it anywhere you like. For now, I’m placing it in the root directory of my Jekyll project (just a note that _site is a sub-directory in this project)
How do I create the application/ routes so that I can do a cf push to it? You don’t need to do anything – once the manifest.yml is set up, everything is done for you when you do the cf push

This is a sample manifest.yml with the above assumptions in place.

---
applications:
- name: xyz-123-blog
  memory: 64M
  host: xyz-123-production
  path: _site/
  buildpack: https://github.com/cloudfoundry/staticfile-buildpack.git
  stack: cflinuxfs2

Now, we can get it online. Navigate to the root directory of your Jekyll site and build the site so that the output is created in _site – then, do cf2 push and wait for it to get done.

I’ve extracted a few of the lines from the command line and split them into sections for easy reference here.

Step 1 – Set up everything on Bluemix: correct stack, correct buildpack, create project, create application and bind route to application

E:\blog>cf push
Using manifest file E:\projects\blog\jekyll\onghu-uno\manifest.yml
Using stack cflinuxfs2...
Creating app xyz-123-blog in org YOUR_ORGANIZATION / space YOUR_SPACE as YOUR_LOGIN...
Creating route xyz-123-production.au-syd.mybluemix.net...
Binding xyz-123-production.au-syd.mybluemix.net to xyz-123-blog...

Step 2 – Upload the files

Uploading xyz-123-blog...
Uploading app files from: E:\blog\_site
Uploading 5.3M, 77 files
Done uploading

Step 3 – Start the instance/ server

Starting app xyz-123-blog in org YOUR_ORGANIZATION / space YOUR_SPACE as YOUR_LOGIN...
-----> Downloaded app package (5.4M)
    Cloning into '/tmp/buildpacks/staticfile-buildpack'...
    Submodule 'compile-extensions' (https://github.com/cloudfoundry/compile-extensions.git) registered for path 'compile-extensions'
Cloning into 'compile-extensions'...
Submodule path 'compile-extensions': checked out '6fc96370a0c95fb3ac22d47a4436152a38bed540'
-------> Buildpack version 1.3.14
Using Nginx version 1.11.6
Downloaded [https://buildpacks.cloudfoundry.org/dependencies/nginx/nginx-1.11.6-linux-x64.tgz]
-----> Using root folder
-----> Copying project files into public/
-----> Setting up nginx
-----> Uploading droplet (8.0M)

Step 4 – Looks like all is OK

1 of 1 instances running
App started
App onghu-blog was started using this command `sh boot.sh`

Step 5 – Final status

requested state: started
instances: 1/1
usage: 64M x 1 instances
urls: xyz-123-production.au-syd.mybluemix.net
last uploaded: Fri Dec 30 13:42:16 UTC 2016
stack: cflinuxfs2
buildpack: https://github.com/cloudfoundry/staticfile-buildpack.git

     state     since                    cpu    memory      disk          details
#0   running   2016-12-30 09:42:55 PM   0.0%   6M of 64M   11.7M of 1G

That is all there is to it actually – your site should be available at whatever is your equivalent of http://xyz-123-production.au-syd.mybluemix.net – the URL for your application will be at: http://[ROUTE].[REGION_PREFIX].mybluemix.net

If you go to the dashboard now, you will see your app’s status there – it the dashboard is at https://console.au-syd.bluemix.net/dashboard/apps or similar depending on your region.

Updating the Buildpack (needed in 2020)

[Updated: 25 Jan 2020] This post was written in 2017 and if you followed the instructions now (i.e., 2020), you would find that you are unable to deploy your site since it fails. Please see Part 4 on how to update the StaticFile Buildpack. The very brief version of that post is: “in the manifest.yml, change stack: cflinuxfs2 to stack: cflinuxfs3” and it should work.

Adjusting Routes

It’s quite possible that you chose routes that don’t look great now that you’ve set them up and want to put them to use. You can adjust and delete routes later if you want. Here is one way to do this.

At any point do cf routes to see what routes exist for which applications in your account. You’ll see the route (as host) and the domain (region) and the apps attached to these routes.

Create a new route that you prefer. Change the manifest.yml to point to a different route. So, you could change it from xyz-123-production to blog-xyz in the host setting. When you do a cf push after this, it will create the new route and bind your application to this route now. At this point, the same application is available on both URLs. You can see this by doing cf routes again.

You can prevent the old route from pointing to that app any more by unmapping it from the application as so:

cf unmap-route xyz-123-blog au-syd.mybluemix.net -n xyz-123-production

This breaks up as:
cf unmap-route
     xyz-123-blog <-- your application name
     au-syd.mybluemix.net <-- the domain name of your application
     -n xyz-123-production <-- the bad URL to remove

You can hold on to that route and map a different application to it at a later point, or just free the route so that it’s not used by your account any more. You do this as below and verify by doing cf routes again.

cf delete-route au-syd.mybluemix.net -n xyz-123-production

This breaks up as:
cf delete-route
     au-syd.mybluemix.net <-- the domain based on your region
     -n xyz-123-production <-- the route you want to get rid of

The Cloudfoundry site has much more on routes

Couple of Things

Just a couple of things to keep in mind:

Depending on how you set up the domains and the routes, you’ll need to update the _config.yml for your Jekyll project to put in the correct value for url so that your assets and links, etc. are correctly generated. In the examples here, we would need to set it as url: 'http://xyz-123-production.au-syd.mybluemix.net' – after that, remember to build your Jekyll site again.
When you make changes to your site, you will need to push these changes to your site. For now, it will be easiest to do a cf push again which will set up the site again just like the first time. There might be an easier way to do this, but I don’t yet know how it’s done (on Day 1, as it is today).

Looking ahead

You’ll probably want to attach your custom URL to this. This will need a few of the steps outlined at: https://console.ng.bluemix.net/docs/manageapps/updapps.html on the Bluemix site (this is a really good read when you want to do a few more advanced things in running your apps and updating them).

Notepad.ONGHU