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.
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!
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> firstname.lastname@example.org
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: email@example.com 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
bluemix apito 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> firstname.lastname@example.org 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: email@example.com 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
Other things that we need to set up:
- We know that we are using
staticfile buildpackfor 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.ymlgo? 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
_siteis a sub-directory in this project)
- How do I create the application/ routes so that I can do a
cf pushto it? You don’t need to do anything – once the
manifest.ymlis set up, everything is done for you when you do the
This is a sample
manifest.yml with the above assumptions in place.
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.
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.ymlto point to a different route. So, you could change it from
hostsetting. When you do a
cf pushafter 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
- 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 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.ymlfor your Jekyll project to put in the correct value for
urlso 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 pushagain 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).
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).
Here are a few links to other articles and web pages from where some of the information has been collected.
About Jekyll/ Static Sites on Bluemix:
- The most useful reference: https://www.drissamri.be/blog/2015/09/05/hosting-a-jekyll-website-on-bluemix/
About Bluemix/ CloudFoundry:
- About Manifests: https://docs.cloudfoundry.org/devguide/deploy-apps/manifest.html
- About Routes: https://docs.cloudfoundry.org/devguide/deploy-apps/routes-domains.html
- Staticfile Buildpack: http://docs.cloudfoundry.org/buildpacks/staticfile/index.html
- Bluemix page on Updating Apps: https://console.ng.bluemix.net/docs/manageapps/updapps.html
- Getting started tutorial for using Java on Bluemix: http://www.ibm.com/developerworks/cloud/library/cl-bluemix-fundamentals-create-and-deploy-a-java-app-to-the-cloud/index.html
- Another (much older) tutorial that talks about how to Create, deploy, modify and redeploy your first Bluemix App: https://www.ibm.com/blogs/bluemix/2014/12/create-deploy-modify-redeploy-first-bluemix-app/