From 5d43527ed6ca255b39a38cb60131b2e91d817f3b Mon Sep 17 00:00:00 2001 From: Marnanel Thurman Date: Wed, 2 Oct 2019 23:34:59 +0100 Subject: [PATCH] Add installation guide, and rewrite README --- README.rst | 56 ++----------------- docs/installation.rst | 125 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 129 insertions(+), 52 deletions(-) create mode 100644 docs/installation.rst diff --git a/README.rst b/README.rst index aed1296..34250de 100644 --- a/README.rst +++ b/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) diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..1fe95af --- /dev/null +++ b/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.