README for Qvisqve
=============================================================================

This is an authorisation server and identity provider. Specifically,
it implements the OAuth2 client credentials grant. Originally
developed to help development of Qvarn (<http://qvarn.org>). Later on,
we hope to develop this into an OpenID Connect provider with support
for authenticating end users.


Configuration for testing
-----------------------------------------------------------------------------

The `debug.yaml` file contains a sample configuration file for Qvisqve
for debugging and light testing. Use it with the `start_qvisqve`
script.

The config defines one API client, client id `test-client`, with a
client secret of "hunter2".


Requirements
-----------------------------------------------------------------------------

The target environment is currently Debian stretch with
stretch-backports enabled. The software might work elsewhere,
especially later versions of Debian.

You'll want to have Python 3.5 or later.


Running Qvisqve for debugging
-----------------------------------------------------------------------------

At the root of the source tree, run the following:

    ./start_qvisqve debug.yaml

This starts Qvisqve using the Bottle.py built-in debug HTTP server,
instead of gunicorn. This makes it easier to debug the server. If
you'd like to run it with gunicorn instead, add the following line to
`debug.yaml`:

    gunicorn: yes

Then run this:

    ./start_qvisqve debug.yaml

This runs the server with gunicorn. Note that that means it is run in
the background. You will need to kill the process manually.


Running Qvisqve for production
-----------------------------------------------------------------------------

Install Qvisqve and then run:

    start_qvirqve /etc/qvisqve/qvisqve.yaml

This runs Qvisqve using gunicorn. Better, install the `qvisqve.service`
systemd unit and start Qvisqve with that.


Git merging workflow for development
-----------------------------------------------------------------------------

All development will happen on branches other than master. Changes are
merged into master, when they're ready to be included into the next
release. If the feature is not ready to be enabled by default, the
merge will include a feature flag that disables the feature by
default. Merging should ideally happen about daily.

Before a merge happens, the changes to be merged will be reviewed and
OK'd by someone else than the their author. The reviewer does the
merge.

The branch to be merged MUST be rebased onto the commit in master. The
actual merge MUST NOT have any conflicts.

The merge MUST be done using --no-ff, i.e., with a merge commit, even
if only one commit is being merged. The merge commit MUST say who
reviewed and accepted it, by including a `Signed-off-by` line. If
there are more than one reviewer, they should all be added to the
merge commit.

Every commit in the master branch MUST pass `./check`.

The merge process is described below. It starts after the changes have
been reviewed and are ready to be merged.

* `git checkout feature-branch`

  Check out the changes to be merged.

* `git checkout -b feature-branch-rebase`

  Create a new branch, where it's safe to rebase.

* `git rebase master`

  Rebase onto master. Resolve any conflicts. Hopefully there aren't
  any.

* `git checkout master`

  Checkout master, which is where the changes will be merged to.

* `git merge --no-ff --no-commit feature-branch-rebase`

  Merge, without committing the changes.

* `./check`

  Run tests. If there are any problem, abort merge process.

* `git commit -s`

  Commit the merge, adding the `Signed-off-by` line to the commit
  message. The merge commit message should summarise the changes made.


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

Qvarn in its entirety is copyright by its authors, and released under
the GNU Affero General Public Licence, version 3, or later.

    Qvisqve - an authorisation server and an identity provider
    Copyright (C) 2018  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/>.