README.md 3.9 KB
Newer Older
1 2
Keel
====
3

4
[project] | [code] | [tracker]
5

6 7 8 9 10
A Django-based middleware application (with a user-facing web interface)
for managing services, resources and subscription-based accounts on a
Liberty Deckplan Host (LDH). The reference implementation for LDH
middleware. Tailored for services operated by Purism SPC, but ready to
be modified and deployed anywhere, by anyone.
11

12 13
Installation
------------
14

15 16 17
Follows an opinionated installation process (specifically expecting
one-instance-per-server), but includes a number of configuration
options.
18

19
See [SETUP.md] for prerequisites and instructions.
20 21 22 23

Usage
-----

24
* Start Django site as a system service, or with `./manage.py runserver`
25 26
* Visit <https://example.com> and follow the login or registration
  links.
27 28 29
  * If registration is closed, you will have to create LDAP credentials
    another way.
* Manage user profile at <https://example.com/accounts/profile/>
30

31 32 33
Models
------

34
![Database model diagram](models.png)
35

36 37 38 39
Model diagram generated with:

    ./manage.py graph_models --all-applications --group-models \
    --verbose-name --output models.png
40

41 42
Build wheel package (and optionally upload)
-------------------------------------------
43 44 45 46

Follow these instructions to build LDH as a Python package:

```
47
  $ apt-get install git libsasl2-dev libldap2-dev libssl-dev python3-dev virtualenv gcc python3-pip
48 49 50 51 52 53 54 55 56 57 58 59
  $ git clone https://source.puri.sm/liberty/ldh_middleware.git
  $ cd ldh_middleware
  $ pipenv install --dev
  $ pipenv shell
  $ python setup.py sdist bdist_wheel
```

If everything works as expected you should end up with the files:
* `ldh_middleware-<version>-py3-none-any.whl`
* `ldh_middleware-<version>.tar.gz`
under dist/ directory.

60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113

You can now optionally upload the created Python package to PyPI using twine:

```
  $ twine upload dist/*
```

Build Debian package
----------------------

This section details the steps that need to be taken to build a Debian
package. We used Debian Stretch to build the package but using any
other Debian based distribution should generate a valid package for
that distribution.

Install Ruby packages and configure the user environment for Ruby 2.4.0:

```
$ sudo apt-get install rbenv ruby-build
$ rbenv install 2.4.0
$ rbenv global 2.4.0
```

Install FPM gem:

```
$ rbenv exec gem install fpm
```

Install the tools needed to create a virtual environment and install
LDH from PyPI:

```
$ sudo apt-get install python3-pip virtualenv libsasl2-dev libldap2-dev libssl-dev
$ sudo pip3 install virtualenv-tools3
$ pip3 install --user setuptools
```

Now we can build a Debian package from the LDH version available in PyPI by running:

```
$ make debpypi
```

or we can build a Debian package with the sources available in our directory by running:

```
$ make debsource
```

After a successful execution you will get a `ldh-middleware_<VERSION>_amd64.deb` file.

You can use `make clean` to remove the virtual environment and the .deb file created.

114 115
Sharing and contributions
-------------------------
116

117 118
Keel (LDH middleware)  
<https://source.puri.sm/liberty/ldh_middleware>  
119
Copyright 2017-2018 Purism SPC  
120
SPDX-License-Identifier: AGPL-3.0-or-later
121

122 123
Shared under AGPL-3.0-or-later. We adhere to the Community Covenant
1.0 without modification, and certify origin per DCO 1.1 with a
124
signed-off-by line. Contributions under the same terms are welcome.
125 126

For details see:
127

128
* [COPYING.md], license notices
129 130
* [COPYING.AGPL.md], full license text
* [CODE_OF_CONDUCT.md], full conduct text
131 132 133
* [CONTRIBUTING.DCO.md], full origin text

<!-- * [CONTRIBUTING.md], additional contribution notes -->
134 135 136

<!-- Links -->

137 138 139
[project]: https://source.puri.sm/liberty/ldh_middleware
[code]: https://source.puri.sm/liberty/ldh_middleware/tree/master
[tracker]: https://source.puri.sm/liberty/ldh_middleware/issues
140 141 142 143 144 145
[SETUP.md]: SETUP.md
[COPYING.AGPL.md]: COPYING.AGPL.md
[CODE_OF_CONDUCT.md]: CODE_OF_CONDUCT.md
[CONTRIBUTING.DCO.md]: CONTRIBUTING.DCO.md
[COPYING.md]: COPYING.md
[CONTRIBUTING.md]: CONTRIBUTING.md