From 6a69a22bde788b9dcd8d80314aadddfe3287a1c7 Mon Sep 17 00:00:00 2001 From: Marnanel Thurman Date: Fri, 2 Oct 2020 22:29:20 +0100 Subject: [PATCH] update installation documentation, and note about bowler-heavy --- README.md | 4 +++ docs/bowler-heavy.md | 23 ++++++++++++++++ docs/installation.md | 63 ++++++++++++++++++++++++-------------------- 3 files changed, 62 insertions(+), 28 deletions(-) create mode 100644 docs/bowler-heavy.md diff --git a/README.md b/README.md index d785076..5e3a5b7 100644 --- a/README.md +++ b/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. diff --git a/docs/bowler-heavy.md b/docs/bowler-heavy.md new file mode 100644 index 0000000..ea112e2 --- /dev/null +++ b/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. diff --git a/docs/installation.md b/docs/installation.md index d333a90..398f1d1 100644 --- a/docs/installation.md +++ b/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.