This repository has been archived on 2024-05-31. You can view files and clone it, but cannot push or open issues or pull requests.
devicehub-teal/README.md

107 lines
3.7 KiB
Markdown
Raw Normal View History

2018-06-10 17:58:27 +00:00
# Devicehub
Devicehub is a distributed IT Asset Management System focused in
reusing devices, created under the project
[eReuse.org](https://www.ereuse.org).
2018-06-10 17:58:27 +00:00
Our main objectives are:
- To offer a common IT Asset Management for donors, receivers and IT
professionals so they can manage devices and exchange them.
This is, reusing and ultimately recycling.
- To automatically recollect, analyse, process and share
(controlling privacy) metadata about devices with other tools of the
eReuse ecosystem to guarantee traceability, and to provide inputs for
the indicators which measure circularity.
- To highly integrate with existing IT Asset Management Systems.
- To be decentralized.
Devicehub is built with [Teal](https://github.com/bustawin/teal) and
[Flask](http://flask.pocoo.org).
2018-06-20 21:32:42 +00:00
## Installing
2018-06-10 17:58:27 +00:00
The requirements are:
- Python 3.5.3 or higher. In debian 9 is `# apt install python3-pip`.
2018-09-05 09:23:31 +00:00
- PostgreSQL 9.6 or higher with pgcrypto and ltree.
In debian 9 is `# apt install postgresql-contrib`
- passlib. In debian 9 is `# apt install python3-passlib`.
- Weasyprint requires some system packages.
[Their docs explain which ones and how to install them](http://weasyprint.readthedocs.io/en/stable/install.html).
2018-06-10 17:58:27 +00:00
2018-06-20 16:24:10 +00:00
Install Devicehub with *pip*: `pip3 install ereuse-devicehub -U --pre`.
2018-06-10 17:58:27 +00:00
## Running
2018-09-16 11:53:07 +00:00
Download, or copy the contents, of [this file](examples/app.py), and
2018-07-17 18:57:29 +00:00
call the new file ``app.py``.
2018-06-10 17:58:27 +00:00
2018-09-16 11:53:07 +00:00
Create a PostgreSQL database called *devicehub* by running
[create-db](examples/create-db.sh):
2018-10-30 08:28:38 +00:00
- In a Debian 9 bash terminal, execute the following two commands:
1. `sudo su - postgres`.
2018-10-30 08:28:38 +00:00
2. `bash examples/create-db.sh devicehub dhub`,
and password `ereuse`.
- In MacOS: `bash examples/create-db.sh devicehub dhub`,
and password `ereuse`.
2018-06-20 21:32:42 +00:00
Create the tables in the database by executing in the same directory
where `app.py` is:
2018-06-10 17:58:27 +00:00
2018-06-20 21:18:15 +00:00
```bash
$ flask init-db
```
2018-06-20 16:24:10 +00:00
2018-06-20 21:18:15 +00:00
Finally, run the app:
2018-06-20 21:32:42 +00:00
2018-06-10 17:58:27 +00:00
```bash
$ flask run
```
The error `flask: command not found` can happen when you are not in a
*virtual environment*. Try executing then `python3 -m flask`.
2018-06-10 17:58:27 +00:00
See the [Flask quickstart](http://flask.pocoo.org/docs/1.0/quickstart/)
2018-06-20 16:24:10 +00:00
for more info.
2018-06-20 21:18:15 +00:00
2018-06-20 21:32:42 +00:00
## Administrating
2018-06-20 21:18:15 +00:00
Devicehub has many commands that allows you to administrate it. You
can, for example, create a dummy database of devices with ``flask dummy``
or create users with ``flask create-user``. See all the
2018-06-21 15:39:40 +00:00
available commands by just executing ``flask`` and get more information
2018-07-02 10:52:54 +00:00
per command by executing ``flask command --help``.
## Understand the software
See the [docs](docs/index.rst) to understand how the software works and
the design principles.
### Use the API
Checkout [Swagger](https://app.swaggerhub.com/apis/ereuse/devicehub/0.2)
to see the schemas and endpoints (we are working in making it
interactive).
Use postman as an example of how to use the API.
[![Run in Postman](https://run.pstmn.io/button.svg)](https://documenter.getpostman.com/view/254251/RWEnmFPs)
2018-07-17 18:57:29 +00:00
## Testing
To run the tests you will need to:
1. `git clone` this project.
2018-09-16 11:53:07 +00:00
2. Create a database for testing executing `create-db.sh` like
the normal installation but changing the first parameter
2018-10-30 08:28:38 +00:00
from `devicehub` to `dh_test`: `create-db.sh dh_test dhub` and
password `ereuse`.
2018-09-05 09:19:36 +00:00
3. Execute at the root folder of the project `python3 setup.py test`.
## Generating the docs
1. `git clone` this project.
2018-09-05 09:23:31 +00:00
2. Install plantuml. In Debian 9 is `# apt install plantuml`.
3. Execute `pip3 install -e .[docs]` in the project root folder.
2018-09-05 09:19:36 +00:00
3. Go to `<project root folder>/docs` and execute `make html`.
Repeat this step to generate new docs.
2018-11-06 13:49:16 +00:00
To auto-generate the docs do `pip3 install -e .[docs-auto]`, then
execute, in the root folder of the project
`sphinx-autobuild docs docs/_build/html`.