trustchain-oc1-orchestral/devicehub-teal
Archived
10
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

Merge pull request #213 from RubenPX/PR-Initial-setup

Browse source 
Add development setup & convert README.rst to Markdown
This commit is contained in:
Santiago L 2022-04-06 17:37:43 +02:00 committed by GitHub
parent 3a05e96d21 554d79d2f9
commit 63d99998a2
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 191 additions and 162 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

134
README.md Normal file
View file

@ -0,0 +1,134 @@
#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 [dependencie](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):
```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:
```bash
$ export dhi=dbtest; dh inv add --common --name dbtest
```
Finally, run the app:
```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:
```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:
```bash
$ sudo su - postgres
$ bash $PATH_TO_DEVIHUBTEAL/examples/create-db.sh devicehub dhub
```
Initialize the database:
```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.
```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:
```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:
```bash
$ alembic edit <revision_id>
```
Apply migrations using:
```bash
$ alembic -x inventory=dbtest upgrade head
```
Then to go back to previous db version:
```bash
$ alembic -x inventory=dbtest downgrade <revision_id>
```
To see a full list of migrations use
```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`.

159
README.rst
View file

@ -1,159 +0,0 @@
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``.

54
development-setup.md Executable file
View file

@ -0,0 +1,54 @@
# Setup developement project
## Installing
complete this steps from [README - Installing](README.md#installing)
## Setup project
Create a PostgreSQL database called devicehub by running [create-db](examples/create-db.sh):
- Start postgresDB
- `bash examples/create-db.sh devicehub dhub, and password ereuse.`
- `cp examples/env.example .env`
Create a secretkey and add into `.env`
```bash
echo "SECRET_KEY=$(python3 -c 'import secrets; print(secrets.token_hex())')" >> .env
```
Using the dh tool for set up with one or multiple inventories. Create the tables in the database by executing:
```bash
export dhi=dbtest; dh inv add --common --name dbtest
```
Create a demo table
```bash
export dhi=dbtest; dh dummy
```
copy `examples/app.py` to project directory:
```bash
copy examples/app.py .
```
## Run project
Run the app
```bash
export FLASK_APP=app.py; export FLASK_ENV=development; flask run --debugger
```
Finally login into `localhost:5000/login/`
- User: user@dhub.com
- Pass: 1234
## Troubleshooting
- If when execute dh command it thows an error, install this dependencies in your distro
- `sudo apt install -y libpango1.0-0 libcairo2 libpq-dev`

4
examples/app.py
View file

@ -20,5 +20,5 @@ app.register_blueprint(labels)
# NOTE: enable by blueprint to exclude API views
# TODO(@slamora: enable by default & exclude API views when decouple of Teal is completed
csrf = CSRFProtect(app)
csrf.protect(core)
csrf.protect(devices)
# csrf.protect(core)
# csrf.protect(devices)

2
setup.py
View file

@ -24,7 +24,7 @@ setup(
packages=find_packages(),
include_package_data=True,
python_requires='>=3.7.3',
long_description=Path('README.rst').read_text('utf8'),
long_description=Path('README.md').read_text('utf8'),
install_requires=[
'teal>=0.2.0a38', # teal always first
'click',