Platform hopping

From uCtrl
So, this story now has a new chapter — seeing as I'm right back where I started; with MediaWiki...

In 2018 I changed platform for my website, a lot. This the third time; from self-made to Jekyll, to Ghost, and now to Hugo. With a lot of trial and error in between. Here is what happened.

The beginning

I first started to write about my electronics projects on the web back in 2006, using WordPress and the tilhol.net domain. February 2007 I migrated to MediaWiki and changed the domain to jensencorp.no, which was the name of my small company at the time. All content at this point was in Norwegian.

Late 2008 I started to translate all content to English and January 2009 I got the uctrl.net domain, still on MediaWiki. It was mostly good; creating and editing pages was easy, but I found making index pages and bulk updates to be a bit too manual for my taste. And the site was completely decoupled from my self-made PHP logistics system, so any change to a project would have to be updated two places. So I set out to make something myself…

The self-made

I had a simple self-made PHP logistics system that kept track of all my electronics projects, what parts I used and the stock levels. It had a really crappy design, and spaghetti code like you would not believe. I decided to rebuild it, using the Laravel framework. The sit would have a public front-end so that all my projects could be internally tracked and publicly shared with the same web app.

I made my first git check-in August 2014, and after eight months of programming, the site went “live” in May 2015, still on the uctrl.net domain. I choose to put live in quotes here because even though the site was up, it didn’t have any public content yet… I figured I would rewrite all project descriptions and repost them. A pretty major undertaking that I would eventually give up…

September 2016 I got the uctrl.io domain and migrated my site shortly after.

I continued to improve the site and re-post my previous projects, but I eventually got fed up with it. It was taking all my spare time, not leaving anything for working on new projects. I wanted to shift focus; for the website to be someplace to write about my projects, not be my only project.

Try 1; Jekyll

I started to search for an alternative website platform — one where I could spend time documenting, not build the platform itself; freeing up time to work on other projects again. I chose Jekyll; and got a working website working reasonably quick. February 2018 I posted the following message:

I’ve decided to shut down my uCtrl.io website. I’m on a mission to reduce time-consuming tasks that are keeping me from doing what I love with my limited spare time. And sadly I was spending more time maintaining uCtrl.io than building and documenting my projects.

So back to basics; I will keep documenting and publishing things I work on and find fascinating, only on a simpler platform. That is why I am setting up a simple static website using Jekyll, and dropping the uCtrl name and domain.

All AVR projects documented on uCtrl.io were built between 2005 and 2012, those pages have not been migrated. Instead of spending time documenting things from the past, I want to focus on recent and ongoing projects like my homelab.

Oh, and I also switched the domain; now it was thomasjensen.me. All was good with the world, the weight of the previous website project was off my shoulders. I could work on other things again. As stated in the quote above I also dropped old projects that I had re-posted, and focused on the new stuff. I was quite happy with the Jekyll setup; I could export parts lists from the logistics system as data files, and show them on my project pages. I had a good system for in-lining images and showing image galleries.

However, it didn’t last. I never got comfortable with Jekyll, and on several occasions, I broke something trying to do an update to Jekyll itself or the theme I was using. And some operations, like adding images to the galleries, was a very manual process that took a lot of time.

Instead of trying to fix the issues I was facing — I decided to migrate again…

Try 2; Ghost

I was very impressed with Ghost; I got it up and running within no time, and writing was super easy. The Ghost editor is just excellent! July 2018 I posted the following message:

(…) Since February however, I’ve found that maintaining a Jekyll website was more work than I was willing to put in. Don’t get me wrong, Jekyll is a wonderful and incredibly customizable platform. But I was really looking for something even simpler, where I didn’t have to install plugins and edit source files.

I read about Ghost, tried it, loved it, and decided to switch to it. It just works, I can just write, and it looks good out of the box. Even though I like to tinker with things I want the blog to “just work,” and Ghost seems to do precisely that :)

As for changing the domain yet again, this time from thomasjensen.me back to uctrl.net. I just really like uctrl and have since I got it back in 2009. The “u” represents both μ (micro) and you, “ctrl” is of course control. Both meanings appeal to me.

And I was back to using the uctrl.net domain, blog.uctrl.net to be exact. A few things that I found was not super easy with Ghost was the image handling — I had to manually open each image in an image editor, resize it, save it and upload it. And I had to copy and paste project parts lists from the logistics system… So again my logistics system and the website was decoupled.

Another thing I lost moving from Jekyll to Ghost was site search; on Jekyll, I had a pretty decent setup using Algolia’s free plan. But on Ghost, it didn’t seem as easy to implement, and I didn’t bother with it. I soon realized that, at least for me, site search is an essential way of navigating, and not adding it was a mistake.

I’m a coder, and tinkerer, not primarily a writer. So I quickly started missing being able to tweak and adjust the website, and the coupling with the logistics system. By September 2018 I still hadn’t posted anything new on my Ghost blog, so I reevaluated by choice of platform — and went searching yet again.

The platform hunt

At this point, I was obviously platform hopping, so I took my time to map out my requirements. And thoroughly evaluate the options before changing the platform yet again. These were my requirements;

  • Markdown
  • Git backed storage
  • Easy image handling
  • Loose structure

Wiki.js

I very briefly tried Wiki.js but moved on. It seemed a bit young and immature, and I wasn’t sure what direction it would go. It looked like a one-person show, and the feature list for the upcoming 2.0 release contained a lot of things that I didn’t need, like support for more back-end storages.

DokuWiki

After looking at multiple wiki solutions I boiled it down to MediaWiki or DokuWiki, I knew MediaWiki quite well and decided I didn’t want to go down that route again. So I spun up a DokuWiki container and started playing with it. And I liked it; I liked it a lot. It had many of the things I was looking for, but there were a few things I didn’t like:

  • No markdown support without using plugins, and the ones I found didn’t seem great.
  • Development seemed to have slowed, even halted maybe?
  • Plugins were needed even for pretty basic functionality.
  • A lot of plugins seemed like they are not maintained anymore, kind of a bad sign I think.

So I posted a question on Reddit if there was any reason not to use DokuWiki. Lots of people were in favor of DokuWiki, and particularly the fact that it stored everything as files. However, someone made a suggestion that I try BookStack, I looked at it, and liked it.

BookStack

After trying BookStack I concluded that I would use it over DokuWiki. I liked the clean and uncluttered look and the idea of books on shelves with chapters and pages. It had a nice markdown editor with live preview; handling attachments, and images were easy. It was also built using Laravel which I know moderately well, as it is the framework I use for my logistics system.

I didn’t like the database backend, that made it more difficult to input data from other sources without using the editor. Also, I eventually found the shelf, chapter, book, and page structure to be a bit rigid for some of my use cases.

So I eventually decided to look further…

Grav

Next out was Grav; this was suggested in my Reddit post, which was how I learned about it. I liked it a lot; it checked a lot of my boxes.

  • Markdown
  • Flat file, git backed
  • Image handling and processing
  • Completely customizable structure
  • Lots of maintained plugins and themes

I decided that Grav would be my next platform, took a theme I liked, made some modifications to it, and built a structure that made sense. Again; all was good with the world. I even posted this message on my Ghost blog:

So, I seem to be platform hopping… I only recently moved from Jekyll to Ghost, and now I am moving again. This time to Grav; it all makes sense in my head. The reason for another change is the same as before; time. As a blogging platform Ghost is excellent, in fact; it’s fantastic. The best I’ve come across. But as a documentation library, Grav seems better and more flexible.

And this is where the time factor comes in; I am already documenting all my projects and setups in a private wiki system. But I almost never find the time or prioritize, to make a blog post about it. I don’t see the blogging part of it as a great use of my time…

All I needed to do now was to migrate the data from my Ghost blog…

Well, a few months went by, and I didn’t get around to it. The thought just kind of put me off. Eventually, I decided that I needed to rethink my platform decision, again, or get the content moved. I decided on the former…

Try 3; Hugo

I wanted to do another dig into static page generators; I like the idea; build it and host it anywhere, can’t crash or be hacked. Having already tried, and not liked, Jekyll I decided to have a look at Hugo. I pulled the binary and had it up and running after 10 minutes — after I figured out that I needed a theme :p

I was impressed, properly impressed! It’s fast, customizable, has a high development rate, good community, and growing popularity. It even has image processing! I was able to take a theme and modify it without getting lost in stylesheets, asset pipelines, and Gems.

I was even able to make shortcodes that pulls data straight from the API of my logistics system. That is a considerable advantage; if I ever swap out any parts on a project, the project page will update on the next build — automatically! :D

I’m also spending some time making helper scripts that minimize the time I have to spend doing things like gathering and resizing images and videos.

Here are some of the things I like:

  • It’s fast!
  • The image processing and page resources is awesome!
  • Being a static site generator; everything is files, which I can edit and manipulate however I want.
  • Load data as JSON or CSV from external resources.
  • High development rate, responsive developers.
  • Active community and forums.
  • No asset pipeline, allowing me to define it myself.

I’m starting to sound like a broken record at this point, but I will try to post more in the future on how I use Hugo. How I pull data from the logistics system and how my image processing is set up.

As I am finishing up this post, I am pretty close to replacing the Ghost blog. And yet again, I am making a domain change; this time I am changing to uctrl.org. As I previously wrote, I like the uCtrl name, meaning both μ/micro control (microcontroller) and you control (self-hosting, automation, privacy). Since I already have a few network services on uctrl.net, I figured uctrl.org was a good use for this site. If you are curious as to why I chose to use www — I might explain that in the future post :)

Update: I later changed the domain again; now it’s uctrl.dev, without the www.

Thoughts

Deciding to drop the logistics system as my public website was the right decision, it allows me to spend more time on projects that I enjoy. And it took away the stress I was feeling about maintaining and developing the site.

Not having time to do new projects because you are caught up in displaying and documenting your old stuff is not productive, and needed to stop. I still use the logistics system internally, as just that; a logistics system, so the time I put into it was not wasted.

Moving from Jekyll to Ghost was probably a bad decision, I’m quite sure I could have made Jekyll work for me. But it’s easy to search for something new, instead of fixing what you have. Ghost was not right for my needs, but it’s a pretty impressive piece of software.

Procrastination

Writing is something I have to decide to do, rather, force myself to do. That is probably true for a lot of people. I think I’ve been quick to blame the platform for my inability to sit down and commit myself to a few hours of typing.

Only time will tell if history will repeat itself; that I don’t write much here either… But I’m feeling optimistic, and having the option of automating things with scripts and shortcodes will allow me to keep the tedious tasks to a minimum.

Since I started with Hugo; I’ve been able to sit down and concentrate on writing. I’m finding that once I get going, it begins to flow after a while. And doing it regularly also seems to make a tremendous difference :)

The secret of getting ahead is getting started. -Mark Twain

Overthinking structure

During my platform testing, I did a lot of thinking about the site structure. How many levels, and how to group it all:

docs/
    linux/
        arch/
        debian/
    homelab/
        computers/
        network/
    opnsense/
    cctv/
    electronics/
        projects/
        lab/
about/
    me/
    website/

I spent so much time thinking about it in fact — that it became a hindrance. I was hesitant to proceed because I was worried I would get it wrong, and it would be a pain in the ass to fix later. Then I remembered a quote I read on Twitter:

Work finally begins when the fear of doing nothing exceeds the fear of doing it badly. -Alain de Botton

I decided to keep the structure as flat as possible, and not reflect the menu structure in the URLs. So Homelab could be below Projects in the top-bar menu. However, its URL is still on the root level; /homelab. I also decided not to distinguish page and post URLs; they are both at the root level.

That made me less concerned about future structural or organizational changes; because, as far as the URLs go, it doesn’t matter.

Simplicity makes me happy. -Alicia Keys