Hosting software documentation

posted by Jeff | Friday, September 11, 2020, 5:00 PM | comments: 0

When I productized (we make up words in my line of work) POP Forums earlier this year, I wanted to a simple way to update and write documentation. For the open source version, I was just using the built-in plumbing that GitHub provides for "pages," which takes markdown files and makes them into a static site using Jekyll. That works well enough, but for the commercial version I needed to park it somewhere that I had more control.

Initially, I used Nuxt.js because it seemed pretty good at generating a static site, and it was easy enough to automate it because you just run an npm command over your code. I really wanted to use something markdown based, but none of the solutions were as simple as I would have liked. This one at least was just using straight up HTML, so the templating and what not was easily taken care of. I wasn't thinking about it at the time, but at that point I could have just as easily used Razor pages in ASP.NET Core for about the same thing. But cool, I learned how to use some different tooling.

Then I moved everything to Linux app services, and the support site broke. The short story is that while Windows app services all run over IIS, a web server, that isn't the case on Linux. It just runs whatever platform you want, and under the hood binds listeners to the containers it makes. For .Net Core, it hooks up to Kestrel. Node, PHP, Java all work similarly. At first I tried to just let node handle it using PM2, but it wouldn't reliably do it. It could be something I was doing wrong, but it spontaneously started serving folder lists or not resolving deep links as if it were only a Vue app.

In this case, I just cut my losses and copied the HTML into Razor pages with a layout parent. It took like five minutes, and another five to spin up a new build/deploy pipeline. Trying to optimize with straight HTML may have been chasing nothing, since Kestrel is so fast anyway. I ended up doing this for the static asset sites that feed images to CoasterBuzz and PointBuzz as well, because just using PM2 wasn't doing any 302's or caching.

It was still worth it moving everything to the Linux app services, and I'm saving about $50 per month with twice the memory and CPU resources.


Comments


Post your comment: