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

David Seaward's avatar
David Seaward committed
4
[project] | [code] | [tracker] | [wiki]
5

David Seaward's avatar
David Seaward committed
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 130 131 132 133 134 135 136 137 138 139 140 141 142
Runing tests
------------

The testing libraries require access to the files provided by the `slapd` package.

```bash
apt install slapd
```

You might want to disable the sldap service if you run the tests on your local development machine:

```bash
sudo systemctl stop slapd.service && systemctl status slapd.service
```

143 144
Sharing and contributions
-------------------------
145

David Seaward's avatar
David Seaward committed
146 147
Keel (LDH middleware)  
<https://source.puri.sm/liberty/ldh_middleware>  
David Seaward's avatar
David Seaward committed
148
Copyright 2017-2019 Purism SPC  
149
SPDX-License-Identifier: AGPL-3.0-or-later
150

151 152
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
153
signed-off-by line. Contributions under the same terms are welcome.
154 155

For details see:
156

157
* [COPYING.md], license notices
158 159
* [COPYING.AGPL.md], full license text
* [CODE_OF_CONDUCT.md], full conduct text
160 161 162
* [CONTRIBUTING.DCO.md], full origin text

<!-- * [CONTRIBUTING.md], additional contribution notes -->
163 164 165

<!-- Links -->

David Seaward's avatar
David Seaward committed
166 167 168
[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
169
[wiki]: https://source.puri.sm/liberty/ldh_middleware/wikis/home
170 171 172 173 174 175
[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