GitBook is a tool for using Markdown to write books, which are converted to dynamic websites or exported to static formats like PDF. GitBook also integrates with Git and GitHub, adding a social element to the book creation process.
OpenShift is a Platform as a Service (PaaS) for hosting web applications. GitBook exports books into interactive HTML websites and those books can be hosted on OpenShift. OpenShift automatically provides all the capabilities that are boring and complicated to configure so you can concentrate on the book creation process.
To make OpenShift even easier for this purpose, I built a QuickStart for GitBook. With this QuickStart, OpenShift becomes a build server and creates a website for you as part of the deployment process. This releases you from installing all the necessary dependencies of GitBook on your machine to build the book into a presentable form.
The QuickStart is at Github. The README describes the basic steps needed to get started.
The book creation process and the GitBook specifics are out of the scope for this article. I will use an existing open-source book and deploy it to OpenShift.
In the top panel, you will see several icons. Starting on the left, there is a link to the GitHub repository the book resides in. You can use the second icon to hide/close the left drawer. Then there is an interactive search capability to provide quick navigation thorough the book. In the center is the book's title.
On the right side, we can see again the close integration with GitHub. Finally, on the very right, social buttons provide a quick and easy way to share the book with your friends via various social networks.
Below the top panel, there is a contents overview on the left and the main space where the book contents are presented. On the left/right sides of the content are quick links to allow you to move to the previous/next chapter.
It's a very simple, yet effective design.
Deploying GitBook on OpenShift
Before we start, you need an OpenShift account. Learn more about OpenShift and sign up for an account. The account is free and allows you to deploy three books (web applications) for free. If you squash multiple books into one application, then you can deploy even more ;).
First, let's create a new OpenShift application. The QuickStart builds on top of the PHP-5.4 application cartridge. We don't need PHP, but the cartridge provides a preconfigured Apache instance capable of serving our static content generated by the GitBook tool. Once the command to create the application has executed, we change into the new Git repository cloned during the app creation process.
rhc app create jsbook php-5.4 --from-code=https://github.com/openshift-quickstart/gitbook-quickstart.git
Now the code of the book is in the repository and the OpenShift parts are in place. The last required step is to change some configuration for the QuickStart. Open the CONFIG.sh file with a text editor and set the name of the GitHub repository for your book. In my case the file would look like this:
That's it. Now we deploy the book to OpenShift by committing the changes to your Git repository and pushing them to OpenShift.
git add .
git commit -m "My first book"
git push origin master
You will see the messages from the build process. Once the push finishes your book is ready. Access it using a web browser. In my case, the URL is:
rhc app show also shows the URL for your app. The URL for your book will have the same form, but mjelen will be your namespace instead (you set this when you ran the command
Read more about GitBook in the documentation, where you will learn how to structure a book and get the best from the functionality provided by GitBook. This simple example shows how OpenShift hides the complexity of building websites and allows you to focus on the content.
Let me know if you write your own book.