TODO merge with devicehub | devicehub adapted to trustchain oc1 orchestral (dpp branch)
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.
Go to file
Cayo Puigdefabregas 67d7e27cf9 adding view of receives 2020-11-19 21:04:14 +01:00
.github/workflows adding codecov 2020-10-02 12:01:10 +02:00
docs Minor fixes to generate documentation correctly 2020-03-17 18:42:53 +01:00
ereuse_devicehub adding view of receives 2020-11-19 21:04:14 +01:00
examples add decouple to config the system 2020-09-29 09:42:05 +02:00
tests resolve conflict 2020-10-29 19:19:33 +01:00
.gitignore add tmp to gitignore 2020-10-07 18:36:37 +02:00
LICENSE.txt Add GPLV3 License 2019-06-09 08:48:09 +02:00
MANIFEST.in Better installation; add example_app 2018-07-07 18:51:15 +02:00
README.rst add decouple to config the system 2020-09-29 09:42:05 +02:00
alembic.ini Update README 2020-05-15 20:14:00 +02:00
requirements.txt add decouple to config the system 2020-09-29 09:42:05 +02:00
setup.cfg Enhance testing config 2018-09-16 15:56:20 +02:00
setup.py import __version__ instead of open file __init__ 2020-09-22 11:57:39 +02:00

README.rst

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Devicehub
#########
Devicehub is a distributed IT Asset Management System focused in reusing
devices, created under the project
`eReuse.org <https://www.ereuse.org>`__.

This README explains how to install and use Devicehub.
`The documentation <http://devicehub.ereuse.org>`_ explains the concepts
and the API.

Devicehub is built with `Teal <https://github.com/ereuse/teal>`__ and
`Flask <http://flask.pocoo.org>`__.

Installing
**********
The requirements are:

-  Python 3.7.3 or higher. In debian 10 is ``# apt install python3``.
-  `PostgreSQL 11 or higher <https://www.postgresql.org/download/>`__.
-  Weasyprint
   `dependencies <http://weasyprint.readthedocs.io/en/stable/install.html>`__.

Install Devicehub with *pip*:
``pip3 install -U -r requirements.txt -e .``.

Running
*******
Create a PostgreSQL database called *devicehub* by running
`create-db <examples/create-db.sh>`__:

-  In Linux, execute the following two commands (adapt them to your distro):

   1. ``sudo su - postgres``.
   2. ``bash examples/create-db.sh devicehub dhub``, and password
      ``ereuse``.

-  In MacOS: ``bash examples/create-db.sh devicehub dhub``, and password
   ``ereuse``.

Configure project using environment file (you can use provided example as quickstart):                    
.. code:: bash 
   
   $ cp examples/env.example .env

Using the `dh` tool for set up with one or multiple inventories.
Create the tables in the database by executing:

.. code:: bash

   $  export dhi=dbtest;  dh inv add --common --name dbtest

Finally, run the app:

.. code:: bash

   $ export dhi=dbtest;dh run --debugger

The error bdist_wheel can happen when you work with a *virtual environment*.
To fix it, install in the *virtual environment* wheel
package. ``pip3 install wheel``

Multiple instances
------------------
Devicehub can run as a single inventory or with multiple inventories,
each inventory being an instance of the ``devicehub``. To add a new inventory 
execute:

.. code:: bash

   $ export dhi=dbtest;  dh inv add --name dbtest

Note: The ``dh`` command is like ``flask``, but
it allows you to create and delete instances, and interface to them
directly.


Testing
*******
1. ``git clone`` this project.
2. Create a database for testing executing ``create-db.sh`` like the
   normal installation but changing the first parameter from
   ``devicehub`` to ``dh_test``: ``create-db.sh dh_test dhub`` and
   password ``ereuse``.
3. Execute at the root folder of the project ``python3 setup.py test``.


Migrations
**********
At this stage, migration files are created manually.
Set up the database:

.. code:: bash

   $ sudo su - postgres
   $ bash $PATH_TO_DEVIHUBTEAL/examples/create-db.sh devicehub dhub

Initialize the database:

.. code:: bash

   $ export dhi=dbtest; dh inv add --common --name dbtest

This command will create the schemas, tables in the specified database.
Then we need to stamp the initial migration.

.. code:: bash

   $ alembic stamp head


This command will set the revision **fbb7e2a0cde0_initial**  as our initial migration.
For more info in migration stamping please see https://alembic.sqlalchemy.org/en/latest/cookbook.html


Whenever a change needed eg to create a new schema, alter an existing table, column or perform any
operation on tables, create a new revision file:

.. code:: bash

   $ alembic revision -m "A table change"

This command will create a new revision file with name `<revision_id>_a_table_change`.
Edit the generated file with the necessary operations to perform the migration:

.. code:: bash

   $ alembic edit <revision_id>

Apply migrations using:

.. code:: bash

   $ alembic -x inventory=dbtest upgrade head

Then to go back to previous db version:

.. code:: bash

   $ alembic -x inventory=dbtest downgrade <revision_id>

To see a full list of migrations use

.. code:: bash

   $ alembic history


Generating the docs
*******************

1. ``git clone`` this project.
2. Install plantuml. In Debian 9 is ``# apt install plantuml``.
3. Execute ``pip3 install -e .[docs]`` in the project root folder.
4. Go to ``<project root folder>/docs`` and execute ``make html``.
   Repeat this step to generate new docs.

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