k4ever/k4ever/docs/install.rst

123 lines
4.0 KiB
ReStructuredText

.. This is the install documentation for a typical k4ever setup.
Installation
============
This is the installation manual for all the parts of k4ever.
k4ever Webinterface + API
-------------------------
The k4ever webinterface is a Django application. You will need some sort of
webserver and something that runs python code.
Dependencies
````````````
- django >= 1.3
- django-piston
- easy-thumbnails
- django-auth-ldap (if you want ldap support)
All of these are available via pip.
Webserver Configuration
```````````````````````
In this example configuration we will use apache2 + mod_wsgi, but there are
many other choices. These are described in Django's docs at `deploying Django
<https://docs.djangoproject.com/en/dev/howto/deployment/>`_.
k4ever has static files which should be served by the webserver directly, so
be sure this happens for the media/ directory.
Here is an apache2 example configuration::
<VirtualHost *:80>
ServerName k4ever.example.com
ServerAdmin k4ever@example.com
DocumentRoot "/home/k4ever/k4ever/"
Alias /media/ /home/k4ever/k4ever/k4ever/media/
<Location /media>
Options +FollowSymlinks
Options -Indexes
</Location>
# wsgi
WSGIScriptAlias / /home/k4ever/k4ever.wsgi
WSGIDaemonProcess k4ever user=k4ever group=k4ever processes=5 threads=1
WSGIProcessGroup k4ever
WSGIPassAuthorization On
</VirtualHost>
.. note::
You might want k4ever to be only reachable via https as k4ever's webinterface
and API depend upon password authentication. Not having encrypted connections
to your webserver will cause password loss.
Configuration
`````````````
Copy over the settings.py.template to settings.py. You can edit all the
settings fitting to your needs. Most of them are django switches, documented
`here <https://docs.djangoproject.com/en/dev/topics/settings/>`_. Some of them
are k4ever specific and have some inline documentation.
The **SECRET_KEY** variable has to be set by you. Just set it to something long
and kind of random. 60 characters should be sufficient.
If you want to add LDAP-Support to your instance of k4ever, edit the ldap
part of the config and make sure you have django-auth-ldap installed. All
users logging in via LDAP are added to djangos user database on login. They
have an invalid password, so they only can login via ldap. For more
documentation about this subject, look at django-auth-ldap's documentation.
If you want to see more settings (the parts we think nobody needs to change)
take a look at settings_default.py. DON'T overwrite them in there as it might
cause a *git pull* to fail, just put them in your settings.py and they will
get overridden.
Barcode-Client
--------------
The Barcode-Client is an interface to k4ever which can run on a dedicated
computer/laptop.
Dependencies
````````````
- python
- simplejson
- a terminal
Configuration
`````````````
You'll need a user/password combination in k4ever, so go to k4ever's admin
page and add a new user which is member of the *Plugin* group. Additionally
you need an entry for the Barcode-Reader to appear on the settings page.
All this can be accomplished by calling the *install.py* with the path
to your k4ever django installation::
python install.py ../k4ever/
At this point the Barcode-Client has no configuration file. All you have to do
is to set three environment variables according to your setup::
export BARCODE_PLUGIN_USER=yourpluginuser
export BARCODE_PLUGIN_PASS=yourpluginpass
export BARCODE_PLUGIN_URL=https://path-to.your/api2/
Afterwards you can start the Barcode-Client with *python freitagskasse.py*.
If you have a Barcode-Scanner: Normally barcodescanners just act as a normal
keyboard. Just let it type the barcodes into the Barcode-Client and everything
should work.
If you have a RFID-Reader: Most RFID-Cards have an ID which can be used to
authenticate against k4ever. A user needs to take this ID and put it in the
authblob section. For an RFID_Reader to work with k4ever you can use the
*rfid_keypresser.py*, which reads all input from the reader and translates
them to X keypresses.