update installation documentation, and note about bowler-heavy

README.md

@@ -15,3 +15,7 @@ but there will be.
 * [Source control](https://gitlab.com/marnanel/kepi)
 * [The bug tracker](https://gitlab.com/marnanel/kepi/issues)
 * [kepi threads on the activitypub forums](https://socialhub.activitypub.rocks/c/software/kepi/32)
+
+## Trivia
+
+* [bowler-heavy](docs/bowler-heavy.md) was a historical course change that may still affect the state of the codebase.

docs/bowler-heavy.md

@@ -0,0 +1,23 @@
+# bowler-heavy
+
+*(This may require knowledge of [the structure of kepi's modules](modules.md).)*
+
+In February 2020 I realised kepi had gone off-course. Bowler, the ActivityPub module,
+was capable of handling *any* ActivityPub message. Trilby, the Mastodon module,
+was merely an interface to Bowler.
+
+That was fair enough, but kepi is supposed to be a microblogging platform, and
+it wasn't trivial to turn the ActivityPub data into users and statuses.
+In addition, it was rather slow.
+
+I put all this into a branch called `bowler-heavy`, and set about turning the tables.
+In the new branch, `trilby-heavy`, all microblogging data was held by Trilby,
+and Bowler only handled as much of the ActivityPub protocol as was necessary
+to run a microblogging platform. `trilby-heavy` was later merged into `main`.
+
+It's possible that `bowler-heavy` could be of use to someone who wanted to
+build a more general ActivityPub system. The branch remains, and you're
+welcome to use it!
+
+The current version of Bowler is derived from the version in `bowler-heavy`,
+and some extraneous code remains.

docs/installation.md

@@ -1,15 +1,34 @@
-Installing kepi
-===============
+# Installation
 
-**This may be out of date**
+**This may be out of date. See [this thread by Dr. Quadragon about installation](https://mastodon.ml/@drq/104956749009106205).**
 
 kepi is still pre-alpha software, so installation is still a
 little fiddly at present.
 
 If anything here doesn't work, [please raise an issue about it](https://gitlab.com/marnanel/kepi/issues/new).
 
-Set up a virtual environment
-----------------------------
+## Dr. Quadragon's installation commands
+
+ * python3 -m venv kepienv
+ * apt-get install python3-venv
+ * python3 -m venv kepienv
+ * source kepienv/bin/activate
+ * git clone https://gitlab.com/marnanel/kepi.git
+ * apt-get install git
+ * source kepienv/bin/activate
+ * git clone https://gitlab.com/marnanel/kepi.git
+ * cd kepi
+ * pip install -r requirements.txt
+ * quit
+ * apt-get install build-essential python3-dev
+ * source kepienv/bin/activate
+ * cd kepi
+ * pip install -r requirements.txt
+ * python manage.py test
+
+# Older installation instructions (to merge in)
+
+## Set up a virtual environment
 
 Start out by setting up a *virtual environment*-- in other words,
 a sandbox so that you don't affect everything else on the machine.
@@ -31,8 +50,7 @@ source kepienv/bin/activate
 
 Your prompt should now have `(kepienv)` at the start.
 
-Grab kepi from gitlab
----------------------
+## Grab kepi from gitlab
 
 Now you're going to get hold of the kepi source code:
 
@@ -47,8 +65,7 @@ new directory named `kepi`. So, go into it.
 cd kepi
 ```
 
-Get the dependencies
---------------------
+## Get the dependencies
 
 Python's package manager `pip` should make this fairly straightforward.
 All *you* have to do is type:
@@ -57,8 +74,7 @@ All *you* have to do is type:
 pip install -r requirements.txt
 ```
 
-Test kepi before you start using it
------------------------------------
+## Test kepi before you start using it
 
 Now, before you start using kepi for real, make sure it works!
 
@@ -71,8 +87,7 @@ If everything passes, we can go on. If not,
 as before,
 [please raise an issue](https://gitlab.com/marnanel/kepi/issues/new).
 
-Set up the database
--------------------
+## Set up the database
 
 Set up an empty database by typing
 
@@ -83,23 +98,17 @@ python manage.py migrate
 This will create a SQLite database called `kepi.sqlite3` in the `kepi` directory.
 (You can use other database systems as well, but this is the default.)
 
-```
-python manage.py kepi-users --create me
-```
-
-Now you have a user called `@me`.
-
-```
-python manage.py kepi-post --actor me "Hello world."
-```
+**XXX This section is out of date. It used to use management commands,
+but those don't exist any more because of [bowler-heavy](bowler-heavy.md).
+It's difficult to explain what to do here: creating a superuser is necessary but will result
+in an unmatched TrilbyUser. [Issue 18 has all the details](https://gitlab.com/marnanel/kepi/-/issues/18).**
 
 And now you've posted your first status.
 
 Unfortunately, nobody can see it, because you haven't yet set up the webserver.
 So, let's go on to that.
 
-Set up the webserver
---------------------
+## Set up the webserver
 
 kepi interfaces with the webserver using a system called `gunicorn` (which is
 short for "green unicorn"). You've already installed gunicorn along with the
@@ -112,15 +121,13 @@ gunicorn kepi.wsgi
 gunicorn is now listening on port 8000 of your computer, which is the
 default.
 
-Check it works
---------------
+## Check it works
 
 Now you can point a browser at
 [http://localhost:8000/users/me](http://localhost:8000/users/me)
 and you should see the JSON form of the user `@me` you created earlier.
 
-Going on from here
-------------------
+## Going on from here
 
 gunicorn itself isn't suitable for facing the public internet.
 You'll need to put something like nginx in front of it.