Docker + Sphinx Bootstrap

Date: 2016-06-24

I built this repository for hosting my technical blog + resume + work portfolio. I containerized the sphinx-bootstrap repository so that on startup it will convert any rst files mounted from a host volume directory into themed, mobile-ready html.

I use this repository for hosting and rendering rst as html on my blog:

https://jaypjohnson.com

Docker Hub Image: jayjohnson/sphinx-bootstrap

Overview

This project started because I wanted to write content and not worry about formatting. When the container starts it converts reStructuredText Markup rst files into readable, static html. It does this by using the python Sphinx bootstrap documentation generator built from Sphinx + bootstrap. Once containerized, I could focus my time on content (like this post). As a fan of data-driven products, I added configurable integration points for Google Analytics and Google Search Console. I like that out-of-the-box the sphinx-bootstrap-theme comes with support for multiple bootswatch themes and there are even more themes available from the bootswatch repository and bootswatch website. Additionally it creates well-formatted, mobile-ready blost posts and web pages.

Integrating with Google Analytics

1. Set your Google Analytics Tracking Code to the ENV_GOOGLE_ANALYTICS_CODE environment variable before container creation

   During container startup the environment variable ENV_GOOGLE_ANALYTICS_CODE will be automatically installed into the default html layout on every page across your site

Integrating with Google Search Console

1. Automatic sitemap.xml creation

   When the container starts or you manually rebuild the html content it will automatically build a sitemap.xml from any files ending with a .rst extension in the repository’s root directory. This file is stored in the environment variable ENV_DOC_OUTPUT_DIR directory. This is handy when you want to integrate your site into the Google Search Console and it should look similar to: https://jaypjohnson.com/sitemap.xml

Getting Started

By default this container assumes there is a sphinx-ready source directory in /opt/blog/repo/

Building

To build the container you can run build.sh that automatically sources the properties.sh file:

$ ./build.sh
Building new Docker image(docker.io/jayjohnson/sphinx-bootstrap)
Sending build context to Docker daemon 48.64 kB
Step 1 : FROM centos:7
 ---> 904d6c400333

...

Removing intermediate container 4381745389cb
Successfully built 724130d8b97f
$

Here is the full command:

docker build --rm -t <your name>/sphinx-bootstrap --build-arg registry=docker.io --build-arg maintainer=<your name> --build-arg imagename=sphinx-bootstrap .

Start the Container

To start the container run:

$ ./start.sh
Starting new Docker image(docker.io/jayjohnson/sphinx-bootstrap)
d321c432272cc61de3270ef302ef2f269610d70238274479bda711ef9d11c564
$

Looking into the start.sh you can see that there are a few defaults taken from the properties.sh file:

$ cat start.sh
#!/bin/bash

source ./properties.sh .

echo "Starting new Docker image($registry/$maintainer/$imagename)"
docker run --name=$imagename -v /opt/blog:/opt/blog -d $maintainer/$imagename

exit 0
$

Test the Container

1. Check the container is running with:

   $ docker ps
   CONTAINER ID        IMAGE                         COMMAND                  CREATED             STATUS              PORTS               NAMES
   d321c432272c        jayjohnson/sphinx-bootstrap   "/root/containerfiles"   9 minutes ago       Up 9 minutes                            sphinx-bootstrap
   $
   

2. If the container started and generated the html correctly there should be a sitemap.xml file:

   $ ls /opt/blog/repo/release/sitemap.xml
   /opt/blog/repo/release/sitemap.xml
   $
   

Environment Variables

If you are looking to configure the composition and containers, here are the available environment variables used by the containers:

Variable Name	Purpose	Default Value
ENV_DEFAULT_ROOT_VOLUME	Path to shared volume for static html, js, css, images, and assets	/opt/blog
ENV_DOC_SOURCE_DIR	Input directory where Sphinx processes rst files	/opt/blog/repo/source
ENV_DOC_OUTPUT_DIR	Output directory where Sphinx will output the html files	/opt/blog/repo/release
ENV_BASE_DOMAIN	Your web domain like: https://jayjohnson.com	https://jaypjohnson.com
ENV_GOOGLE_ANALYTICS_CODE	Your Google Analytics Tracking Code like: UA-79840762-99	UA-79840762-99

Want to add a new blog post?

1. Open a new new-post.rst file in the source directory

2. Add the following lines to the new new-post.rst file:

   ==================
   This is a New Post
   ==================
   
   My first blog post
   

3. Edit the index.rst file and find the Site Contents section

4. Add a new line to Site Contents toctree section containing: new-post

   Here is how mine looks after adding it to the index.rst

   Site Contents
   -------------
   
   .. toctree::
       :maxdepth: 2
   
       new-post
       python
       work-history
       contact
       about
   

   Note

   One nice feature of the sphinx framework is it will automatically label the dropdown link with the first Title section found inside the file.

5. Save the index.rst file

6. Deploy and Rebuild the html files

   Inside the websphinx container I included a deploy + rebuild script you can run from outside the container with:

   $ docker exec -it websphinx /root/containerfiles/deploy-new-content.sh
   

7. Test the new post shows up in the site

   $ curl -s http://localhost:80/ | grep href | grep toctree | grep "New Post"
   <li class="toctree-l1"><a class="reference internal" href="new-post.html">This is a New Post</a></li>
   <li class="toctree-l1"><a class="reference internal" href="new-post.html">This is a New Post</a></li>
   $
   

Rebuilding HTML content without restarting the docker container

I added a rebuild-html.sh script that handles converting the rst files into html without a container restart. To rebuild the content for a new revision or deployment just run:

$ ./rebuild-html.sh
Rebuilding HTML with command: /root/containerfiles/deploy-new-content.sh
Done rebuilding html
$

Stop the Container

To stop the container run:

$ ./stop.sh
Stopping Docker image(docker.io/jayjohnson/sphinx-bootstrap)
sphinx-bootstrap
$

Or run the command:

docker stop sphinx-bootstrap

Licenses

This repository is licensed under the MIT license.

Sphinx Bootstrap Theme is licensed under the MIT license.

Bootstrap v2 is licensed under the Apache license 2.0.

Bootstrap v3.1.0+ is licensed under the MIT license.

Thanks for reading,

Jay

Want to learn more?

• Email me

• Contact Information