So, I made a thing.
I’ve been meaning to host projects I’ve written on my own server, and it’s now available (and has been for a little while, but whatever). The tool I’ve made to do so is here, along with some of my rationale, but I figure I’ll talk about it a bit here.
The site itself exists for both practical and ideological reasons. On the practical side, I don’t have a particularly reliable network connection, so having hosting locally available is helpful. It also lets me control the interaction with the rest of the systems I use (scm and build), and gives me the freedom to alter factors without moving or splitting up my hosting.
On the ideological side, I’m a big proponent of the independent web, and I’m not a fan of adding a dependency on third-party silos, especially since none of them come with any real guarantees. It’s hard to discuss that sort of ideology without sounding like a lunatic, so that’s all I’m gonna say for now. The other point worth mentioning is that I rejected all of the existing self-hosting products largely because they were trying to solve a problem that I don’t have.
That last part is multifaceted so I think it’s worth elaborating a little more. There seems to be a bit of a rut in self-hosting solutions, as they all seem to be based around the same sorts of mistaken assumptions. Generally speaking, the self-hosting products I’ve seen have been either scm-specific, trying to do too much, or both. Basically, the authors have seen the success of github and are trying to replicate it. Which is fine, I suppose, if that’s the problem that you have; but I’d wager that most potential users don’t need to self-host a github equivalent.
Speaking for myself, I don’t need user accounts, pull requests, history navigation, or much else. I need to allow people to clone the repository and browse the code. Anything else is handled by the scm tool. Is that boring? Yeah, probably, but it’s solving a problem and not just building something sexy.
So in comes csb. It’s a dead-simple cli tool to build a static website to
host source code. The code is all either go or bash, and the only requirements
for the compiled code is bash, the standard unix utilities, uudecode, and
jq. It’s currently at probably 90% usable,
though I haven’t really tested it outside of my own few machines so there may
be some glaring issues that I just haven’t hit.
When it came down to it, csb doesn’t even need javascript or any dynamic server support at all. Now, it’s currently limited to just git, so cloning a different sort of repository may add server constraints (though I’d hope not), but the code browsing just needs a source tree to be pointed at and the output is 100% static.
csb is designed around assembling simple subcommands into larger features. The hairy safety-concerned parts such as assembling the html are done using go and its template system, while much of the ‘business’ logic is done with relatively simple bash scripts gluing things together. There are a few utility commands that almost deserve their own blog posts, just for how stupidly useful they wound up being (csb-optparse and csb-config in particular might deserve developing into real, general-purpose utilities).
Feature-wise there’s really only one major thing that I’d consider missing, and that’s pretty-printing of the code. Right now it’s just html-escaped, but otherwise preserved as-is in code blocks. I hope to do filetype-specific formatting (eg markdown processing or syntax highlighting) eventually and some of the skeleton exists, it’s just not finished.
On the more minor side is updating an existing site. Right now it will only build from scratch every time, and will in fact error (though not as nicely as it could) if you try to output on top of a previous build. I did actually have this working on my dev machine, but an issue with the git version on my server had me roll it back. I’d like to see it back in eventually, but given that my automated build system is designed around always doing clean builds anyways, this isn’t a big concern for me.
In all, though, I’m happy with csb as it exists. The subcommand ui works well, and the code is isolated enough that I feel comfortable extending it as I go. A big part of that came naturally out of the small-command structure that I built, as I surprised myself with how simple some parts are now that I have some basic building blocks. For example, I have functioning history support on my dev machine in only a small bash script using the components that already exist. I’m not completely happy with it, but the simple fact that it was maybe 15 minutes of work for the first crack speaks well to the design I’ve got.
Now to figure out what my blog’s navigation should look like with more than two links…