Setting Up A Blog In 3 Steps

Posted on Sat 07 November 2020 in Tutorials

Publishing an article like this one on your own website can be done in three straightforward steps.

In a nutshell, the three main steps involved in publishing this article were

  1. Producing the site with Pelican
  2. Dockerizing the site
  3. Deploying to Clever Cloud

Any subset of these steps can be replaced with your preferred alternatives. In other words, you don't have to use Pelican to generate the site, Docker to package it, nor Clever Cloud to run it.

This is a static website, which means that all its artifacts are served straight from files in a web server's file system, in this case the Apache HTTP server running in a Docker container.

The site (i.e. the contents of the aforementioned document root folder) was generated using Pelican, which is a Python-based static site generator. To follow along, you may choose any other way of producing your site, including hand-crafting it. In fact, future versions of this article may be generated using another tool, e.g. one from this list.

Once produced, the site can be packaged in a Docker container, deployed to Clever Cloud and it is online instantly.

If you wish to use your own domain name, I'll provide some hints on how to do this with Clever Cloud.

Let's have a detailed look at the individual steps.

Producing the Site With Pelican

To install Pelican, follow the quickstart guide on the project website. If you are not comfortable with Python, you may want to look for some other site generator. Regardless of which process you've used, I'll assume you have produced your site into a directory called output, as it is the case when using Pelican to generate it. (In the next step, we will, among other things, copy the contents of this directory to the Apache HTTP Server document root.

To test this step locally, you can start Pelican's own web server from the project directory (the one containing the output directory), as indicated in the quickstart guide:

pelican --listen

If you can see your site when pointing a web browser to http://localhost:8000, we are ready for the next step.

Dockerizing the Site

To make the site easily deployable to a variety of cloud providers, we'll package it in a Docker container. This involves writing one of the simplest conceivable Dockerfiles and saving it in the same folder your output folder resides in. The Dockerfile should consist of the following three lines.

FROM httpd:2.4
COPY ./output/ /usr/local/apache2/htdocs/
RUN sed -i -e 's/^Listen 80/Listen 8080/' /usr/local/apache2/conf/httpd.conf

This will instruct Docker to base your image on the official httpd image and copy the contents of your site to the document root of Apache HTTP Server.

As Clever Cloud requires all servers to listen on TCP port 8080 we use a simple sed command to replace the default Apache port from 80 to 8080.

Note that there is no need to configure TLS/SSL as this will be provided by Clever Cloud out of the box.

To test this step, make sure the Pelican server used to test the previous step is not running anymore as we are exposing the same port this time. Then, build and run a Docker container locally (a prerequisite, of course, is to have Docker installed on your box):

docker build -t blog .
docker run --name blog -p 8000:8080 blog

If you can now access your site at http://localhost:8000, we are ready to deploy it to a cloud provider.

Deploying to Clever Cloud

To deploy to Clever Cloud, you will (obviously) need to sign up for an account on their site.

After logging in to your account, initialize a new Docker application by following the wizard you should find (as of this writing) by starting from your Personal Space, then navigating to

Create... -> an application -> CREATE A BRAND NEW APP -> Docker -> etc.

Make sure to choose the appropriate instance count and size, which should probably be the smallest possible values offered at this point.

Once the new application has been initialized, you will have access to a Git repository dedicated to deploying new versions of it. At a minimum, this repo should contain your Dockerfile and the Pelican output directory. Each time you push a change to the repo, the Docker container hosting your site will be rebuilt and redeployed.

The instructions provided by Clever Cloud upon successful completion of the app creation wizard will be something like the following.

git remote add clever git+ssh://git@push-par-clevercloud-customers.services.clever-cloud.com/app_xyz.git
git push -u clever master
# git push -u clever branch:master if you want to push a specific branch

This assumes that you already have a local Git repo that you can augment by adding a new remote, calling it clever. While this approach will work, I prefer cloning the empty Clever Cloud repository locally and adding to it only files necessary for deployment, i.e. the Pelican output and the Dockerfile. I keep all the other files used to generate the site in a separate repository. This avoids pushing unnecessary files to Clever Cloud, which tends to make deployment faster and more secure.

Before we can do any of this, however, we need to setup SSH authentication.

First, generate a new SSH key by following the instructions in the SSH Keys section of your Clever Cloud profile. Assuming you have saved your private key locally without a passphrase under ~/.ssh/id_clevercloud, add the following entry to your ~/.ssh/config

Host cc-deploy
  HostName push-par-clevercloud-customers.services.clever-cloud.com
  User git
  IdentityFile ~/.ssh/id_clevercloud

You can use any name instead of cc-deploy to refer to the Git repository host.

The ssh-keygen command creates another file with the extension .pub which contains your public key. In our example, the file is stored as ~/.ssh/id_clevercloud.pub. Use the contents of this file to add a new SSH key to your Clever Cloud profile.

Note: In all of the following samples, replace app_xyz with your app's ID.

Once you have configured your SSH client and added the public key to Clever Cloud, you need to use the host name you have chosen for the Git repository in a clone command. As we have used cc-deploy in this example, the clone command is:

git clone git+ssh://git@cc-deploy/app_xyz.git

The app_xyz directory thus created can now be populated with your Dockerfile and the Pelican output directory contents. You can have Pelican produce the site into a specific folder using the -o option. Otherwise you'll have to copy the output directory to the Git repo every time the site changes. Once the new files have been added to the local repository, launching (the latest version of) your site is simply a matter of running:

git push

To test this step, first wait for your app to be deployed in your personal space. Once the app has been successfully deployed point your browser to http://app_xyz.cleverapps.io/.

If you can see your site, congratulations!

Optional: Use Your Own Domain

Let's assume you own the domain example.com and want to make the blog accessible at blog.example.com.

  1. Go to the Domain names section of your app's configuration and add blog.example.com to Custom domain names.

  2. Visit your domain provider site and add a new CNAME record for the host name blog.example.com with the value provided by Clever Cloud. For the Paris zone, this is domain.par.clever-cloud.com. at the time of writing.

If everything goes well, your blog should be accessible at https://blog.example.com in a matter of minutes.

Wrap-up

While this may not be the cheapest option at ~ €15 per month, it is a quick and easy way to setup a blog that is fully under your control. What would be your favorite way of building this type of site?

Blog Pelican Docker Clever Cloud Apache HTTP Server Python

Next Post