README.md 4.27 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.

Thomas Markiewicz's avatar
Thomas Markiewicz committed
114 115 116 117 118 119 120 121 122 123 124

Continuous Integration Build
----------------------------

The Debian package is automatically build on every commit. You can get the latest one from the "master" branch like this:
```
wget -O ldh-middleware_master.zip https://source.puri.sm/liberty/ldh_middleware/-/jobs/artifacts/master/download?job=deb
unzip ldh-middleware_master.zip
dpkg -c ldh-middleware_0.0.3_amd64.deb
```

125 126
Sharing and contributions
-------------------------
127

128 129
Keel (LDH middleware)  
<https://source.puri.sm/liberty/ldh_middleware>  
130
Copyright 2017-2018 Purism SPC  
131
SPDX-License-Identifier: AGPL-3.0-or-later
132

133 134
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
135
signed-off-by line. Contributions under the same terms are welcome.
136 137

For details see:
138

139
* [COPYING.md], license notices
140 141
* [COPYING.AGPL.md], full license text
* [CODE_OF_CONDUCT.md], full conduct text
142 143 144
* [CONTRIBUTING.DCO.md], full origin text

<!-- * [CONTRIBUTING.md], additional contribution notes -->
145 146 147

<!-- Links -->

148 149 150
[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
151 152 153 154 155 156
[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