No-framework blog for fun and profit using Bash & CGI

Background

The year is the 2546.

A cataclysmic conflict shattered the delicate balance of power, resulting in a devastating nuclear exchange that changed the course of history. The consequences of that fateful moment continue to reverberate through the ages, casting a long shadow over the survivors who remain.

The Internet how we used to know it, it doesn’t exist anymore. Frameworks like React, Vue, Svelte are long gone and documentations have been forever lost.

You wake up in your room with nothing more than an ancient book from the 1994 showing a bunch of CGI scripts and a Linux box still working in your bedroom.

Suddenly, you want to start a blog.

A blog. As fast as I can.

Even though we’re not living in the Fallout world, some time ago I decided I wanted to quickly publish a blog around ESP8266 programming. If you’re somewhat like me, and your motivation spikes last from 3 to 5 hours, you have to make stuff fast.

Therefore, I quickly summarized in my head the minimum amount of things I needed to have my blog up and running asap:

• A tool allowing me to write posts using Markdown
• Something that turns Markdown pages into HTML
• A way to quickly publish my posts on my VPS to share my knowledge with the world

That’s it.

It turned out I managed to have this blog up and running before my motivation drained completely, and I’m still somewhat proud.

Here’s the result: https://esp8266code.com

If you’re into microcontroller programming (and even if you don’t!), make sure to bookmark it!

Building a minimalistic “template engine”

I almost immediately discarded the option to use any framework. I needed something faster.

Therefore I quickly sketched a template for my posts and another one for the home page, using the awesome Terminal CSS and, with the help of some bash foo, I wrote a small script which will:

1. Pick every Markdown post from the posts folder and transform them into HTML files using the almighty pandoc
2. Rebuild the home page every time there’s a new post showing the N latest posts

As soon as the html folder has been populated, another tiny script will simply upload the updated pages to my VPS using rsync

Yes.. rsync!

Why? Because it’s fast, free and it automatically takes care of uploading just the files that are out of sync between my machine and my VPS. All in a single bash line:

rsync -avz --chown=www-data:www-data --rsync-path="sudo rsync" html templates cgi images js css robots.txt sitemap.xml vps:/var/www/html/esp8266code

There’s only one page which cannot be static: the search page. Indeed, it needs to be generated on the fly based on user input.

Typically, you would have your posts stored in a Database, so that you can easily perform a query to find those posts matching the search string. There are also more sophisticated ways such as ElasticSearch or Algolia to achieve it.

But I’m a lazy guy. Plus, I don’t have a Database. So I thought.. the filesystem is my database.

Yes, grep is the “search engine” I was looking for. Fast, reliable and reminds good memories. So definitely yes, a small script generating a search page on the fly is what I need.

Cool! But how to get the search string from every GET request?

CGI is the (fast!) answer!

CGI: an echo from the past

I can hear your complains already. CGI is not secure. It’s not a best practice anymore. CGI is the devil and so on.

Calm down. It’s only being used to match keywords from a specific folder on the server. It won’t harm anyone (unless some good reviewer spots some hidden weakness!).

Since on my server I’m using Nginx, I’ve used the FastCGI module. And it works flawlessly!

Here’s how I’ve used it in my Nginx virtual host.

FastCGI automatically injects query parameters to your bash scripts through the QUERY_STRING environment variable, so you can easily pick them up from your script. The following excerpt (from search.sh) shows how you can easily extract the search keywords from the search query parameter:

search=$QUERY_STRING
search="${search#*=}"
IFS='+' read -ra keywords <<< "$search"

Then, I only compare the search string against the keywords stored in the HTML metadata. It’s simple and it can be definitely improved, but it was quick and works for me:

  for keyword in "${keywords[@]}"; do
      if grep -q "$keyword" "$file" <<< "$meta_keywords"; then
          # Fill the HTML body template with the search results:
          html_body+="<li><a href="$file">$meta_title</a></li>"
          break
      fi
  done

And that’s all folks!

In conclusion, when it comes to starting a blog, you don’t need to be fixated on using top-notch technology. While cutting-edge tools can certainly enhance your blog capabilities and scalability, it’s important to remember that simplicity can be just as effective for a simple project. Whether you’re armed with a basic laptop, a smartphone, or even pen and paper, what truly matters is the content you create and the passion you infuse into your writing. So, don’t let the absence of high-end technology hold you back from embarking on your blogging journey. Embrace the tools at your disposal, and let your words take center stage.

You can find all the code on GitHub. Feel free to use it as you like!

Also, https://esp8266code.com has been made with this “framework”. Feel free to take a look!

Happy blogging!

💗 If you like what you’ve read feel free to leave a comment
👏 Claps are always appreciated and..
🔖 …don’t forget to subscribe!