distixapi - an online API to a distix repository
=============================================================================

Introduction
-----------------------------------------------------------------------------

distix is a distributed ticketing system based on email and git.
distixapi is (or will be) an HTTP based RESTful API to a distix ticket
repository, on top of which an interactive web application for
reading, managing tickets can be built.

distixapi is pre-ALPHA quality at this time. The only API endpoint
that works is `/version`.


Setup/installation
-----------------------------------------------------------------------------

Install from a Debian package, or start from the command line:

    ./distix-backend --port=8080 --log distix-backend.log --user-file=users.yaml

API users are listed in the "users file", which is in YAML and lookd
like this:

    users:
        liw:
            salt: nacl
            password: ....
            scopes: [get, put]

Above, "liw" is the name of the user, "salt" is a random string for
"salting" the password for that user (should be long and different for
each user), "password" is the encrypted password, and "scopes" should
be the HTTP methods the user is allowed to use (one or both of get and
put).

The password encryption can be done with the `distixapi-encpw`
utility:

    ./distixapi-encpw nacl:clrtxtpw

Here, "nacl" is the salt and should be the same as the salt in the
users file. "clrtxtpw" is the password in cleartext. The output is the
encrypted password.

If installed from a Debian package, the users file is in
`/etc/distix-backend/users.yaml`, unless the default configuration
file has been changed. If you change the users file, you need to
restart the server.


Hacking
-----------------------------------------------------------------------------

distix is written in Python 2 (do not ask for Python 3, it will happen
when it happens).

There are no unit tests yet.

There are some integration tests written for the controller's HTTP
API. To run them, run `./check`. You may add any command line
parameters than `yarn` accepts.


Legalese
-----------------------------------------------------------------------------

While distixapi itself is under the AGPL3+ license (see below), this
license does NOT apply to clients of the HTTP API it provides.

Copyright 2017  Lars Wirzenius

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.