[2023-07-29] git_wiki

[Blog] / 2023-07-29 / git_wiki / #entry.rdf

<awol:Entry
        xml:lang="en"
        xmlns:awol="http://bblfish.net/work/atom-owl/2006-06-06/"
        xmlns:dc11="http://purl.org/dc/elements/1.1/"
        xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
        xmlns:sioc="http://rdfs.org/sioc/ns#"
>
        <dc11:title>Running a Wiki with a Server and Git</dc11:title>
        <dc11:date>2023-07-29T14:19:48-07:00</dc11:date>
        <dc11:abstract rdf:parseType="Markdown"><![CDATA[
Forum software can be intimidating, but a wiki is something you can set
up easily and trivially—so long as you are fine with the editing
interface just being a Git repository.
]]></dc11:abstract>
        <sioc:content rdf:parseType="Markdown"><![CDATA[
In the past few days I’ve set up a new domain here at <cite>Lady’s
Computer</cite>: [`wiki.ladys.computer`][Wiki]. The goal of this site
is to be a public, easily‐editable forum (a <dfn>wiki</dfn>) for myself
and friends to document our thoughts and feelings. This blogpost exists
to formally announce the project, describe its underpinnings, and
describe how you can set one up on your own.

## What Is a Wiki?

In order for this post to make any sense at all, it’s probably first
necessary for me to digress into a bit of wiki philosophizing. Because
[wiki is not Wikipedia][WikiIsNotWikipedia], and a lot of people don’t
really understand what a wiki is *for*.

What I want to emphasize in this post is that a wiki is not a
reference material. *A wiki is a social space.* The etymological root
for <i>wiki</i>, [<i lang="haw">wikiwiki</i>][wikiwiki], is a Hawaiian
word meaning “quick”; the goal of the wiki is to *lower the bar for
social interaction* to be as “quick” as possible. What distinguishes
the wiki from other forms of social media is the form this social
interaction takes. Where·as on a traditional forum, social behaviours
are purely additive, the wiki adds a subtractive component: On a wiki,
you engage in the social practice of *revision* or *refinement*.

Put simply, you write on a wiki **because you want somebody to edit
it.** Editing means deleting the part that is bad and expanding on the
part that is good. Editing can mean taking a page with just a title and
filling it with words. Editing can mean adding a dissenting opinion to
make a strong claim appear more qualified. Editing can mean adding
hyperlinks, both internally (to other wiki pages) and out to the
broader web.

In all this, there is nothing *preventing* a wiki from taking on the
shape of more traditional social media, writing in what is called
“thread mode”. Discourse on a wiki can and probably should begin, in
many cases, as a thread of members posting their thoughts and opinions
to each other on a page. It is common to sign statements which have a
personal component or which one feels particularly strongly about.
But threads also don’t have to *remain* threads. On a wiki, there is
nothing stopping someone from going through and structuring the
conversation into a more coherent, and readable, argument at a later
date.

All wikis keep a log of edits, so nothing is ever lost.

My hope is that the above points make clear the practical utility of a
wiki space for *dialectics*, for critical conversations and discourse,
for evolving development of communal thought, and for a kind of
participatory dialogue which it is harder to make manifest on other
platforms. This *radical* potential of the wiki is completely lost in
sites like Wikipedia and also in the sorts of reference sites that
contemporary big‐name static site generators are typically geared
towards. [Docusaurus][], as one completely arbitrary example, is
entirely lacking in social features for editors to communicate *with
each other*, which, after all, is a wiki’s entire *point*.
(Contemporary static site generators *also*, I think, have failings
which limit their utilities as reference texts, but I will save *those*
thoughts for a different blogpost.)

## Technological Underpinnings

When I first mentioned to my partner that I was « trying to write a
wiki generator », their immediate response was « dont like any of the
existing ones? ». I then had to explain the following points :—

1. The kind of thing I’m trying to do *mostly* doesn’t exist in any
   broadly‐acknowledged, existing form, and

2. If I’m doing this right, the end result should be maybe a thousand
   total lines of code, so I might as well just write it exactly how I
   want it anyway.

To be entirely clear about this, I am not the first person to have this
idea and I am absolutely certain that, for example, the Emacs folks
have been doing this sort of thing with Org Mode for probably decades.
But there are a few *recent* technological developments which I think
have made now a *very good time* for this sort of project, and whose
recency also means that, of course, I will have to write the actual
code to make use of them.

### Git

Well, Git is not new. People have been using Git for a long time, and
people have been building wikis on top of Git as well for a long time.
John MacFarlane’s [Gitit][] is I think a reasonable example of the sort
of thing I am interested in, in terms of its general approach.

What I think *is* relatively new, or at least growing, is the idea that
Git is *sufficient*, that a commandline git interface is *the only
editing interface one needs* for a website of content, especially one
containing zero code. We are in a moment where *nontechnical* use of
Git, Git for writers and not just for programmers, and Git for human
text and not just computer code, seems within reach. This drastically
lowers the bar for what might be considered a reasonable wiki
interface, from a web application to a simple repository which trusted
individuals can access over S·S·H.

This is not at all difficult to set up, and can be done without the
need for *any* additional tools on virtually any server that one might
control.

### Deno

Using a Git repository as a backend means it is desirable to have the
wiki generator be something which can be called as a simple shell
script in a post‐receive hook. Ideally, this script would be something
located and tracked in a different repository, and a single file which
can easily be grabbed and run even if that other repository is bare.

There are of course a great many scripting languages out there which
one could use for this task, but for most of them a problem immediately
emerges in the form of dependency management. [Deno][] is notable, and
extremely favourable for this kind of use·case in my opinion, because
in Deno the problem of dependency management simply does not exist.
Every Deno dependency can be specified as simply a U·R·L, and a single
script file with numerous dependencies can be straightforwardly run
with no external configuration or prerequisite setup or package
installation. And Deno is a fully‐featured Javascript (or, if you
prefer, Typescript) runtime, so you still have all the strengths and
conveniences of a modern programming language, which you wouldn’t have
trying to write this, as some have doubtlessly done, in a Lisp or in
Bash.

### Djot

Because the goal of a *wiki* is to be *quick*, it is a fact
generally‐accepted that the markup language it uses must be
*lightweight*. Because we will be taking the approach of static site
generation, this markup language needs to be trivially, and quickly,
parse·able into an A·S·T which can be easily inspected and transformed
by our generation script. The best‐in‐class for lightweight markup
transformation today is [Pandoc][], whose A·S·T [I have worked with
before][BookGen] and which has a [variant of Markdown][Pandoc/Markdown]
that is highly feature·ful and welsuited to transformation.
Unfortunately, Pandoc is written in Haskell, filters for it are
typically written in Python or Lua, and it both more heavyweight and
more of a dependency nightmare than would really be ideal for this sort
of script.

Fortunately, the creator of Pandoc, the afore·mentioned John
MacFarlane, has developed another markup language with all the
strengths of Pandoc’s Markdown but none of its weaknesses, and has
written a parser implementation for this markup language in Typescript.
It’s called [Djot][]. Djot is still extremely beta software, but it
meets all of our requirements: It is lightweight, fast to process, and
trivially importable in Deno. It has a straightforward A·S·T and was
designed with script‐based transformation explicitly in mind.

## How to Do It

Having decided on the above, I spent a couple of days and threw
together [a wiki‐generation script][GitWikiWeb] which, while messy and
not exactly feature·ful right now, is a usable minimum viable product.
I won’t go into the design decisions of that script here, but I do want
to enumerate how one might *use* it to set up their own wiki site. The
following explanation assumes you have a box running something
relatively unixy and are logged in as a root user.

The first step is to clone the GitWikiWeb repository locally, so that
you aren’t waiting for the network every time you want to build your
wiki. This also enables you to make modifications to the template and
stylesheet, which will almost certainly be necessary. (I recommend
maintaining your changes as a set of patches on top of the upstream
repository, but do whatever you feel most comfortable with.)

The following clones it into `/srv/git/GitWikiWeb` :—

```sh
git clone --bare https://git.ladys.computer/GitWikiWeb.git /srv/git/GitWikiWeb
```

Next, you will want to set up a wiki user on your server, which all of
the editors to your wiki will have access to. The <cite>Pro Git</cite>
book has [a very good explanation of how to create a shared Git
user][GitBook-4.4], so I will just summarize it here.

This adds a `wiki` user and creates its `.ssh` directory :—

```sh
# As the root user…
adduser wiki
su wiki
cd
mkdir .ssh && chmod 700 .ssh
touch .ssh/authorized_keys && chmod 600 .ssh/authorized_keys
```

This sets up the `Wiki` repository which will store your wiki
content :—

```sh
# As the root user…
cd /srv/git
mkdir Wiki
cd Wiki
git init --bare
chown -R wiki:wiki .
```

To prevent wiki users from changing other aspects of the server, set
the login shell for `wiki` to be `git-shell` :—

```sh
# As the root user…
chsh wiki -s $(which git-shell)
```

Now you can add the S·S·H public keys to
`/home/wiki/.ssh/authorized_keys` for everybody you want to be able to
edit your wiki. It is recommended that you prefix these keys with
`no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty ` to
further restrict what capabilities `wiki` users have on your server.

Once you do this, users should be able to clone and contribute to the
wiki from `wiki@yourcomputer.example:/srv/git/Wiki`.

The only thing left to do is to add a `post-receive` hook to
`/srv/git/Wiki/hooks` which will build the site every time somebody
pushes new content. Naturally, this file must be executable. Mine looks
like the following :—

```sh
#!/usr/bin/env -S sh
export GITWIKIWEB=/srv/git/GitWikiWeb
while read oldrev newrev refname
do
  if [ $(git name-rev --name-only --refs=live $refname) = "live" ]
  then
    git archive --remote=$GITWIKIWEB ladys build.js \
      | tar -xO \
      | deno run -A - ~/public $GITWIKIWEB ladys
  fi
done
```

To take this line‐by‐line :—

- `#!/usr/bin/env -S sh` simply runs the file with `sh`.
  I use `/usr/bin/env` here because `sh` is in a different place on my
  local and remote computers.

- `export GITWIKIWEB=/srv/git/GitWikiWeb` provides the location to the
  GitWikiWeb repository that we cloned earlier.

- `while read oldrev newrev refname` loops over all the refs which were
  pushed (there can be multiple) and assigns `$refname` to the name of
  the ref.

- `if [ $(git name-rev --name-only --refs=live $refname) = "live" ]`
  checks to see if the pushed ref was equivalent to the `live` branch.
  `git name-rev` tries to provide a name for its argument, and with
  `--refs=live`, it will prefer `live`. Change “live” to whatever the
  default branch for your wiki is, or edit the file at
  `/srv/git/Wiki/HEAD` to be `ref: refs/heads/live` if you like that as
  the name for the default branch.

- `git archive --remote=$GITWIKIWEB ladys build.js` requests an archive
  of the file `build.js` from the `ladys` branch of the GitWikiWeb
  repository. You will probably want to specify a different branch
  name. By default, this is a Tar file.

- `tar -xO` untars the Tar to standard output.

- `deno run -A -` runs the piped script with full permissions. The
  GitWikiWeb script takes three arguments: ① the location to which the
  wiki should be built, ② the location of the GitWikiWeb repository,
  so that it can request template and configuration files, and ③ the
  branch in the GitWikiWeb repository which files should be requested
  from (this should match the branch name you gave to `git archive`).

…and that’s it! Assuming there is a webserver hosting the content at
`/home/wiki/public/`, the wiki should be live as soon as someone posts
content to it.

My hope is that the above steps make this feel reasonable, and bring
the idea of small, community‐run wikis into a space where they feel
like something one could conceivably do. There has been a lot of noise,
with social media these days being what it is, about bringing back
forum culture, but forum hosting is often complex and involves a
nontrivial amount of sysadminning work. I think bringing back wiki
culture in a limited, low‐tech, grassroots sort of way is a viable
alternative and can satisfy a lot of the same use·cases, sometimes even
better.

It’s only been up for a few days, but so far my wiki at
[`wiki.ladys.computer`][Wiki] has proven this to be an idea with
potential.

[Wiki]: <https://wiki.ladys.computer> "Lady’s Wiki"
[WikiIsNotWikipedia]: <https://wiki.c2.com/?WikiIsNotWikipedia> "Wiki Is Not Wikipedia"
[wikiwiki]: <https://en.wiktionary.org/wiki/wikiwiki> "Wiktionary: wikiwiki"
[Docusaurus]: <https://docusaurus.io/> "Docusaurus: Build optimized websites quickly, focus on your content"
[Gitit]: <https://github.com/jgm/gitit> "Gitit"
[Deno]: <https://deno.land/> "Deno: A modern runtime for JavaScript and TypeScript"
[Pandoc]: <https://pandoc.org> "Pandoc: a universal document converter"
[BookGen]: <https://github.com/BookGen/BookGen> "BookGen"
[Pandoc/Markdown]: <https://pandoc.org/MANUAL.html#pandocs-markdown> "Pandoc User’s Guide § Pandoc’s Markdown"
[Djot]: <https://djot.net/> "Djot (/dʒɑt/)"
[GitWikiWeb]: <https://git.ladys.computer/GitWikiWeb> "🐙🕸️ GitWikiWeb: A Git‐backed wiki"
[GitBook-4.4]: <https://git-scm.com/book/en/v2/Git-on-the-Server-Setting-Up-the-Server> "Pro Git: 4.4 Git on the Server – Setting Up the Server"
[Caddy]: <https://caddyserver.com> "Caddy: The Ultimate Server with Automatic HTTPS"
]]></sioc:content>
        <dc11:rights rdf:parseType="Markdown"><![CDATA[
Copyright © 2023
<a href="https://www.ladys.computer/about/#lady">Lady</a>
<small>[Web Socialist]</small>.
Some rights reserved.

This blogpost is licensed under a <a rel="license"
href="http://creativecommons.org/licenses/by/4.0/"><cite>Creative
Commons Attribution 4.0 International License</cite></a>.
]]></dc11:rights>
</awol:Entry>