Add installation guide, and rewrite README

README.rst

@@ -1,54 +1,6 @@
-django-kepi
-===========
+kepi
+====
 
-kepi is a Django library for ActivityPub, using Python 3.
-It's still at an early stage, and you shouldn't particularly expect anything
-to work properly.
-
-Help is always appreciated.
-
-Purpose
--------
-
-This project has two purposes:
-
- * a Django library for ActivityPub. This is the ```django_kepi``` app.
-
- * a standalone daemon for other local programs to interact with.
-   This is the ```kepi``` project (in the Django sense).
-
-Running it
-----------
-
-Nothing out of the ordinary. Create your virtual environment:
-
-```
-$ python3 -m venv wombat
-$ wombat/bin/activate
-```
-
-If ```python3``` doesn't work, try plain ```python```.
-
-Then go wherever you put the kepi sources, and run the installation:
-
-```
-$ pip -r requirements.txt
-$ python manage.py tests
-$ python manage.py runserver
-```
-
-then check whether you can see anything at [https://127.0.0.1:8000/admin/](https://127.0.0.1:8000/admin/) .
-
-Please don't make kepi's server visible beyond your local network. It's not designed to serve the general internet.
-If you're installing for more than just testing, use nginx or apache to proxy requests.
-
-History
--------
-
-kepi started life as part of [the un_chapeau project](https://gitlab.com/marnanel/un_chapeau).
-un_chapeau is a Mastodon-like system written with Django in Python.
-kepi was split off from this, because it seemed more generally useful.
-
-(All the subsystems of un_chapeau are named after kinds of hat;
-a kepi is a kind of hat worn by French gendarmes.)
+kepi is an ActivityPub daemon, written in Python.
 
+* [Installation guide](docs/installation.rst)

docs/installation.rst

@@ -0,0 +1,125 @@
+Installing kepi
+===============
+
+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
+----------------------------
+
+Start out by setting up a *virtual environment*-- in other words,
+a sandbox so that you don't affect everything else on the machine.
+
+```
+python3 -m venv kepienv
+```
+
+If your system tells you that `python3` isn't available, try plain
+`python`. Python 2 is going away soon, but the command names might
+take a while to catch up.
+
+Now you have your virtual environment set up, you can activate it
+by typing
+
+```
+source kepienv/bin/activate
+```
+
+Your prompt should now have `(kepivenv)` at the start.
+
+Grab kepi from gitlab
+---------------------
+
+Now you're going to get hold of the kepi source code:
+
+```
+git clone https://gitlab.com/marnanel/kepi.git
+```
+
+When git has finished downloading the source, you will have a
+new directory named `kepi`. So, go into it.
+
+```
+cd kepi
+```
+
+Get the dependencies
+--------------------
+
+Python's package manager `pip` should make this fairly straightforward.
+All *you* have to do is type:
+
+```
+pip install -r requirements.txt
+```
+
+Test kepi before you start using it
+-----------------------------------
+
+Now, before you start using kepi for real, make sure it works!
+
+```
+python manage.py test
+```
+
+This will run all the tests, which might take a few moments.
+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 an empty database by typing
+
+```
+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."
+```
+
+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
+--------------------
+
+kepi interfaces with the webserver using a system called `gunicorn` (which is
+short for "green unicorn"). You've already installed gunicorn along with the
+other dependencies. So we can start it up:
+
+```
+gunicorn kepi.wsgi
+```
+
+gunicorn is now listening on port 8000 of your computer, which is the
+default.
+
+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
+------------------
+
+gunicorn itself isn't suitable for facing the public internet.
+You'll need to put something like nginx in front of it.
+This document should explain that, and it will at some point.