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

160 lines
4.2 KiB
ReStructuredText
Raw Permalink Normal View History

2019-06-15 13:08:08 +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>`__.
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*:
2020-06-09 08:33:01 +00:00
``pip3 install -U -r requirements.txt -e .``.
2019-06-15 13:08:08 +00:00
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``.
2020-09-29 07:42:05 +00:00
Configure project using environment file (you can use provided example as quickstart):
.. code:: bash
$ cp examples/env.example .env
2020-06-09 08:33:01 +00:00
Using the `dh` tool for set up with one or multiple inventories.
Create the tables in the database by executing:
2019-06-15 13:08:08 +00:00
.. code:: bash
2020-06-09 08:33:01 +00:00
$ export dhi=dbtest; dh inv add --common --name dbtest
2019-06-15 13:08:08 +00:00
Finally, run the app:
.. code:: bash
2020-06-09 08:33:01 +00:00
$ export dhi=dbtest;dh run --debugger
2019-06-15 13:08:08 +00:00
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,
2020-06-09 08:33:01 +00:00
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
2019-06-15 13:08:08 +00:00
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``.
2020-05-11 08:15:40 +00:00
Migrations
**********
At this stage, migration files are created manually.
Set up the database:
2020-05-15 18:13:49 +00:00
.. code:: bash
$ sudo su - postgres
$ bash $PATH_TO_DEVIHUBTEAL/examples/create-db.sh devicehub dhub
2020-05-15 18:13:49 +00:00
Initialize the database:
2020-05-15 18:13:49 +00:00
.. 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.
2020-05-15 18:13:49 +00:00
.. code:: bash
$ alembic stamp head
2020-05-15 18:13:49 +00:00
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
2020-05-15 18:13:49 +00:00
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:
2020-05-11 08:15:40 +00:00
.. code:: bash
2020-05-15 18:13:49 +00:00
$ alembic revision -m "A table change"
2020-05-11 08:15:40 +00:00
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>
2020-05-11 08:15:40 +00:00
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>
2020-05-11 08:15:40 +00:00
To see a full list of migrations use
2020-05-15 18:13:49 +00:00
.. code:: bash
$ alembic history
2019-06-15 13:08:08 +00:00
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``.