Creating a site with Pelican and Heroku

Utilizing two powerful technologies for easy web publishing

Posted by creatic on Mon 22 April 2019

Creating a site fast and cost-effective

Sometimes you just want to create a new webpage fast, without too much hassle, with having a domain, features like templating capabilities and a simple (and maybe free) hosting solution. This is the case when a static site generator and Heroku comes handy.

There are a bunch of static site generators around. Here I show Pelican as it has all the features I need, but of course choose any of your taste.

What we'll do is setup a site wih Pelican and upload to Heroku with some tiny changes.

Getting the base structure

On Linux follow the instructions to install Pelican

I like to create a new pipenv environment and work inside:

mkdir newsite

cd newsite

pipenv --three

pipenv shell

pip install pelican markdown

or from github: pip install -e "git+https://github.com/getpelican/pelican.git#egg=pelican"

Having the source you can run: pelican-quickstart

Now, build the project base with pelican content

If you run pelican --listen you can check out the base of your page on http://127.0.0.1:8000/

Pelican now created a sub-directory named output This is the html root of your project, so this is the directory your web server should point to. But what about Heroku? Heroku by default does not serve static html projects. So we have to mimic this project to be something more attractive, like e.g. PHP

So create the index.php file with the following contents in the output folder:

<?php header('Location: /index.html');

You also need a composer.json file with the contents {} for the mimic:

touch output/composer.json

Creating the git repo

And now commit the result to git, so we can upload the project to Heroku:

git init

git add .

git commit -am "initial site"

Setup Heroku and push your project

To access Heroku from command line you need The Heroku CLI It is a simple Terminal application using which you can manage your Heroku projects.

Let's just create a new project on Heroku:

heroku login -i

heroku create newsite-com

heroku git:remote -a newsite-com

git subtree push --prefix output heroku master

You can see the trick that makes the .build directory the root of our html project instead of the actual root. We use git subtree for that.

Result

In the end see the result: https://newsite-com.herokuapp.com/index.html

Simple and straightforward isn't it? Now you can create .html files in the templates directory, pages in the pages directory.

Custom domain

In case you have a custom domain to add for your app, just use:

heroku domains:add www.newsite.com

Then point your domain to newsite-com.herokuapp.com at your dns provider.

See details at: https://devcenter.heroku.com/articles/custom-domains

Git repo of the whole project

In case you want to save the the whole project into git you can do it in the usual way e.g.:

git remote add origin git@gitlab.com:test.user/newsite.git

git push origin master

You will have the full directory tree, including the output folder.