When you treat docs like code, you want to deploy that “code” to a web site. In our case, these code source files are doc source files. We want to see how something like a documentation site looks on a web site with a static site generator (SSG) like Jekyll. I had been practicing these deployment techniques while working on OpenStack, which offers open source cloud computing services. I needed to practice so I could get better, and also practice was the best way to learn this type of technical problem-solving—by doing. You could try these same techniques by deploying a site yourself.
Outline of overall deployment steps
The way I approached the practice effort was to:
- Find credentials for a cloud (or two). AWS, Google Cloud Platform, Azure, Oracle Cloud Infrastructure, or IBM Cloud are all viable options in 2021.
- Determine which web services to install on the cloud servers to launch there.
- Find deployment orchestration templates that launch the right combination of web services to make the site, deploying Ruby, Jekyll, and NGINX, using Ansible.
- Test, test, test. Test some more.
- Try out Docker locally, then get the cloud server working. This step took a while while I worked out the Linux user permissions needed for installing Ruby with the compatible version needed. Ruby environments can be worked out though and in the end I triumphed.
- Set up the cloud server as a git remote, then push the website to the git remote, building the HTML and copying the files to the web server. In a way, it’s a small implementation of GitHub Pages I suppose.
Discussion about the adventure
Hear me talk about my excitement trying out docs deployment in this video clip from the original on thenewstack.io. In it, I talk to Alex Williams, founder of TheNewStack.io, about my adventures at the OpenStack Summit in Barcelona. Thanks to Alex for the permission to re-post and for asking about my latest work.
Resources
Deploying Apps on OpenStack, Things we found while playing around is the title of talk. The deck is available on Slideshare at http://www.slideshare.net/annegentle/deploying-apps-on-openstack.
Ansible code example
The Ansible code is on GitHub. The YAML file is fairly straightforward, though the tricky parts were in the user permissions.
---
- hosts: jekyll
remote_user: cloud-user
become: yes
become_method: sudo
roles:
- common
- nginx
- git
- jekyll
Jekyll theme: so-simple
The Jekyll theme, so-simple, is on GitHub. I love the simple design and readability of this theme. It also has built-in search capabilities.
Content repository
The content repo is on GitHub. This contains the content for the web site or documentation site.
Video demo
This video demo shows pushing the site to the git remote to update the content.
Looking back on this now, I realize it’s fairly simple, but when you want to discover how something works, sometimes it is best to make a simple prototype. Then you can understand more complex deployments as you continue on your discovery path.