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

David Seaward's avatar
David Seaward committed
4
[project] | [code] | [tracker] | [wiki]
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
Model diagram generated with:

David Seaward's avatar
David Seaward committed
38
    ./ldh_middleware graph_models --all-applications --group-models \
39
    --verbose-name --output models.png
40

David Seaward's avatar
David Seaward committed
41 42 43
Requires GraphViz (`apt install graphviz`) and dev dependencies
(`pipenv install --dev`).

44 45
Build wheel package (and optionally upload)
-------------------------------------------
46 47 48 49

Follow these instructions to build LDH as a Python package:

```
50
  $ apt-get install git libsasl2-dev libldap2-dev libssl-dev python3-dev virtualenv gcc python3-pip
51 52 53 54 55 56 57 58 59 60 61 62
  $ 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.

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 114 115 116

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
117 118 119 120 121 122 123 124 125 126 127

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
```

128 129
Sharing and contributions
-------------------------
130

131 132
Keel (LDH middleware)  
<https://source.puri.sm/liberty/ldh_middleware>  
David Seaward's avatar
David Seaward committed
133
Copyright 2017-2019 Purism SPC  
134
SPDX-License-Identifier: AGPL-3.0-or-later
135

136 137
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
138
signed-off-by line. Contributions under the same terms are welcome.
139 140

For details see:
141

142
* [COPYING.md], license notices
143 144
* [COPYING.AGPL.md], full license text
* [CODE_OF_CONDUCT.md], full conduct text
145 146 147
* [CONTRIBUTING.DCO.md], full origin text

<!-- * [CONTRIBUTING.md], additional contribution notes -->
148 149 150

<!-- Links -->

151 152 153
[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
David Seaward's avatar
David Seaward committed
154
[wiki]: https://source.puri.sm/liberty/ldh_middleware/wikis/home
155 156 157 158 159 160
[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