Build a Static Website Using Python, Pelican, and Docker

In this example I’ll show you how you can build a static website for your open source project on GitHub pages using the combination of Python (language), Pelican (generator), and Docker (environment).  For this type of task, speed is important.  I want to avoid spending time thinking about designing a blog system or implementing a content management system.  My goal with this approach, is to focus on the content, and avoid worrying about installation, setup, or infrastructure.

As far as content creation goes, Pelican supports HTML, Markdown reStructuredText formats and more.  There are many editors out there that will make building content in these formats very simple.  A deeper discussion of formats and editors deserves its own post, so I’m not going to delve into the details here.

Step by Step

Here’s the entire process:

  • Step 1 – First setup and install docker.  I do this on my local system, but you could use any of the various Docker hosting providers as well.

MJJacko's Pelican Image

 

 

  • Step 3 – Next map the Docker volume to one of your local file folders.  This allows you to edit and create your content files, just as you would any other local file.

 

  • Step 4 – The web server included with Pelican will detect any file changes and auto-rebuild your site.  You can see the updates directly by just browsing to the web server’s URL.

GitHub Add content and push

 

  • Step 5 – Once you are happy with your site…ship it!  In this case deployment is done by simply pushing your generated HTML content to the gh-pages branch.

 

  • And done!

Advanced Configuration

While we are avoiding the complexity of a blog or CMS application, there is some configuration that still have to be defined.  However if we bundle these configuration files inside of our docker image we only need to worry about it when we are initially setting up the project, or making environmental changes (which should be fairly infrequent).

Making a docker image requires a docker ‘build’ (Dockerfile) file plus any files that need to be added to the new image.  You can checkout my example on GitHub.

In this case there are 3 important configuration files:

These configuration files are intended to to be a basic minimum to get you running quickly, however you might want to replace them from your own repository.  This is totally fine, however be aware that re-installing requirements in the container will not happen automatically.  You will either need to build a new image, or login to the container, run ‘pip‘ and then use ‘Docker commit‘ to save the image.

Also we will include a bash script that keeps the a running server with the site available.  Otherwise Docker would run once and exit.

With these files in place, actually creating the image is easy, change to your build directory and run: docker build -t user/myrepo:latest .

Once you build the image from the Dockerfile others on your team can use the image directly.  Additionally you can maintain the Dockerfile with source control so that the team can easily contribute any changes to the environment back to it.

With static site generation, a docker managed environment and a GitHub pages hosting solution, building a website is quick, and simple to manage.

Notes

  • Pelican has a large library of plugins that can help address many content publishing needs.  You might be surprised how much you can do with a static site generator!
  • We might add additional build tools in different languages, such as  Ruby’s SASS for CSS development.  These tools can be added to the Docker build process a single time, then when other team members update their environments this will preconfigured.
  • This post relies heavily on GitHub pages, but it’s worthwhile to mention that other static hosting solutions that use Git should work equally well.
Build a Static Website Using Python, Pelican, and Docker

List of Amazing Tech Talks on Software Development

Building computer software is all about ideas. I find quite a bit of inspiration from listening to presentations and tech talks from other people in software development. You should be warned that some people might find the topics below fairly controversial!  But I feel that’s good. To me, if a presentation makes you pause to think and reflect, it is always worth the time to stop and listen.
Continue reading “List of Amazing Tech Talks on Software Development”

List of Amazing Tech Talks on Software Development

Looking ahead: JVM Programming Languages

White laptop with cup of coffee isolated on white

In this article I take a look ahead at the future of four programming languages; Java, Scala, Clojure and Kotlin. All four of these languages are designed to run on the Java Virtual Machine ( JVM ), which is supported on practically every computer operating system. Most recently, JVM programming languages have become popular choices for building cloud applications.
Continue reading “Looking ahead: JVM Programming Languages”

Looking ahead: JVM Programming Languages

Open Source programming environments that make coding easier

A programmer’s life is hard enough keeping up-to-date on the latest technologies, understanding product specifications, and debugging issues. These programming environments help keep programmer sane by offering integrated syntax coloring, auto-completion, debugging tools and more.
Continue reading “Open Source programming environments that make coding easier”

Open Source programming environments that make coding easier