State of the union
Posted:
Haven't updated in a while, so I thought I'd take some time to describe the site in general.
Basic organization
What we have here is a system that strives to be as self-contained as possible in a monolothic docker-compose. By "monolithic", I mean that every container in the docker-compose should be defined and configured right in the same repository. There are a few components that exist as their own repos, but only with good reason.
I want to minimize the moving parts involved in migrating the site. It should be as close as possible to git pull followed by docker-compose up.
emacs org-mode static site
I couldn't live with myself if I didn't use these tools for this. It would hurt my soul. For those not in the know, emacs is a text editor and org-mode is an emacs major mode / file format for documents. Every post on this site exists primarily as an org-mode source file that gets exported to HTML and served directly by the nginx web server. You can see the org-mode files here.
Export is handled by a custom HTML export backend that marks up posts using microformats2 classes so the HTML is easily parsed by tools like mf2py. org-publish is used to build the org files and copy any static files that may be generated. After export, a Makefile takes over which does the following:
- For each .html file, builds a corresponding .mf2.json file containing the output of parsing the file with mf2py.
- For each directory, builds an items.json file containing a list of all the posts described by .mf2.json files.
- For each items.json file, builds a corresponding index.html containing a feed of posts. This will need to be paginated soon, making index2.html and so on when a dir gets too full, but for now it just puts everything in one big file.
Thus each directory ends up with an index.html that is built once and served directly by nginx, no database involved. When a source file hasn't changed, make will do nothing, so only index files whose inputs have changed get rebuilt. The .mf2.json for each post and items.json files for each directory are also served, if you want to see them.
Along with making the HTML files, the build process involves org-roam, which is essentially a system for caching certain properties of org-mode files and headlines in a sqlite database. What I most care about at the moment is that it automatically gathers all the links into a place easily queried by other code, so I don't have to parse for them myself.
Django for apps
There's an of Django running at https://rolledgoats.gg/apps/ for anything that needs a database.
org-roam
A little glue app so that I can access what's in the org-roam database from Django. I use this to gather the links from all the pages and send webmentions.
Webmention
This one defines a Webmention endpoint at https://rolledgoats.gg/apps/webmention/receive. If you host a page that links to a page here, you can send a webmention to that endpoint, and it'll display on the page (eventually: that part isn't set up yet and will be subject to moderation time).
It also acts as a caching webmention sender. There is a management command that gathers links from the org-roam database, sending a webmention when pages change. This isn't actually part of the HTML build system yet, I've just been running it manually.
Wordle
Just a Wordle clone. I like the idea of self hostable games that smaller communities can use without having to be part of a global app, so there'll be more of this kind of thing in the future.
Forĝejo
A standard forĝejo instance hosted at https://sghetti.dev. A couple of the repos here are part of the docker-compose system, but exist as their own repos, namely https://sghetti.dev/goats/rggg-org and https://sghetti.dev/goats/rggg-export.el.
rggg-org is the org-mode sources for the HTML pages on the site. It's a separate repo so that it can have a webhook that publishes any changed HTML files after a push.
rggg-export.el is the emacs lisp source for the custom export backend, so when it changes it rebuilds the whole site, regardless of what has changed.