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.
- Step 2 – Next, run an existing Docker image. I have a great docker image already setup, but of course you could also build your own (see below for ‘advanced’ configuration).
- 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.
- 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!
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).
In this case there are 3 important configuration files:
- requirements.txt – any Python dependencies that are needed
- pelicanconf.py – basic site configuration
- publishconf.py – configuration for static publishing
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.
- 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.