From 3967d6a0c4d6b44d4906909e4bf6398da9612135 Mon Sep 17 00:00:00 2001 From: RubenPX Date: Mon, 4 Apr 2022 12:34:33 +0200 Subject: [PATCH 01/10] Convert readme to markdown --- README.rst | 159 ----------------------------------------------------- readme.md | 140 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 140 insertions(+), 159 deletions(-) delete mode 100644 README.rst create mode 100644 readme.md diff --git a/README.rst b/README.rst deleted file mode 100644 index 1eba57c5..00000000 --- a/README.rst +++ /dev/null @@ -1,159 +0,0 @@ -Devicehub -######### -Devicehub is a distributed IT Asset Management System focused in reusing -devices, created under the project -`eReuse.org `__. - -This README explains how to install and use Devicehub. -`The documentation `_ explains the concepts -and the API. - -Devicehub is built with `Teal `__ and -`Flask `__. - -Installing -********** -The requirements are: - -- Python 3.7.3 or higher. In debian 10 is ``# apt install python3``. -- `PostgreSQL 11 or higher `__. -- Weasyprint - `dependencies `__. - -Install Devicehub with *pip*: -``pip3 install -U -r requirements.txt -e .``. - -Running -******* -Create a PostgreSQL database called *devicehub* by running -`create-db `__: - -- 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 `_a_table_change`. -Edit the generated file with the necessary operations to perform the migration: - -.. code:: bash - - $ alembic edit - -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 - -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 ``/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``. diff --git a/readme.md b/readme.md new file mode 100644 index 00000000..169bbe0d --- /dev/null +++ b/readme.md @@ -0,0 +1,140 @@ +#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 `_a_table_change`. +Edit the generated file with the necessary operations to perform the migration: + +```bash +$ alembic edit +``` + +Apply migrations using: + +```bash +$ alembic -x inventory=dbtest upgrade head +``` +Then to go back to previous db version: + +```bash +$ alembic -x inventory=dbtest downgrade +``` + +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 `/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`. From e1821c3a8e305d07b2936b709cd57c96612ee328 Mon Sep 17 00:00:00 2001 From: RubenPX Date: Mon, 4 Apr 2022 12:35:32 +0200 Subject: [PATCH 02/10] Comment some app.py lines that cause an error Request by @slamora --- examples/app.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/examples/app.py b/examples/app.py index 91b48a59..b0f3bad0 100644 --- a/examples/app.py +++ b/examples/app.py @@ -18,5 +18,5 @@ app.register_blueprint(devices) # 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) From 4656bbf8723f9158bf1ada011564c0502580fb69 Mon Sep 17 00:00:00 2001 From: RubenPX Date: Mon, 4 Apr 2022 12:35:52 +0200 Subject: [PATCH 03/10] add developement setup guide --- developement-setup.md | 55 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 developement-setup.md diff --git a/developement-setup.md b/developement-setup.md new file mode 100644 index 00000000..d2684fbf --- /dev/null +++ b/developement-setup.md @@ -0,0 +1,55 @@ +# Setup developement project + +## Installing + +complete this steps from readme +- #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 python3-pip python3-cffi python3-brotli libpango-1.0-0 libpangoft2-1.0-0` From 3119658098902813b74d99cf80d02fc25fe58443 Mon Sep 17 00:00:00 2001 From: RubenPX Date: Mon, 4 Apr 2022 17:17:07 +0200 Subject: [PATCH 04/10] Update developement-setup.md Co-authored-by: Santiago L --- developement-setup.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/developement-setup.md b/developement-setup.md index d2684fbf..1bb00f18 100644 --- a/developement-setup.md +++ b/developement-setup.md @@ -2,8 +2,7 @@ ## Installing -complete this steps from readme -- #installing +complete this steps from [README - Installing](README.md#installing) ## Setup project From 584f8b990ac117e3b0ff0b0d86fb4ca4df2048b7 Mon Sep 17 00:00:00 2001 From: RubenPX Date: Mon, 4 Apr 2022 17:23:25 +0200 Subject: [PATCH 05/10] change config to set readme.md instead of rst Necesary to build wheel package --- setup.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup.py b/setup.py index 6a0db9b9..9dbedba9 100644 --- a/setup.py +++ b/setup.py @@ -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', From 6b7cf88a2f6c736a7cd614bc02074b5c804516b8 Mon Sep 17 00:00:00 2001 From: RubenPX Date: Mon, 4 Apr 2022 17:25:39 +0200 Subject: [PATCH 06/10] fix typo developement to development --- developement-setup.md => development-setup.md | 108 +++++++++--------- 1 file changed, 54 insertions(+), 54 deletions(-) rename developement-setup.md => development-setup.md (95%) diff --git a/developement-setup.md b/development-setup.md similarity index 95% rename from developement-setup.md rename to development-setup.md index 1bb00f18..4743f2a9 100644 --- a/developement-setup.md +++ b/development-setup.md @@ -1,54 +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 python3-pip python3-cffi python3-brotli libpango-1.0-0 libpangoft2-1.0-0` +# 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 python3-pip python3-cffi python3-brotli libpango-1.0-0 libpangoft2-1.0-0` From c5f006d40fd07ab7b60ccdf5e436550a0f81b846 Mon Sep 17 00:00:00 2001 From: RubenPX Date: Mon, 4 Apr 2022 17:45:04 +0200 Subject: [PATCH 07/10] fix troubleshooting and link --- development-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) mode change 100644 => 100755 development-setup.md diff --git a/development-setup.md b/development-setup.md old mode 100644 new mode 100755 index 4743f2a9..c900574a --- a/development-setup.md +++ b/development-setup.md @@ -51,4 +51,4 @@ Finally login into `localhost:5000/login/` ## Troubleshooting - If when execute dh command it thows an error, install this dependencies in your distro - - `sudo apt install python3-pip python3-cffi python3-brotli libpango-1.0-0 libpangoft2-1.0-0` + - `sudo apt install -y libpango1.0-0 libcairo2 libpq-dev` From 57e35c016fc397c9d76fa94b1e4acf574f0ae991 Mon Sep 17 00:00:00 2001 From: RubenPX Date: Mon, 4 Apr 2022 17:59:51 +0200 Subject: [PATCH 08/10] fix link readme (reviewed) --- readme.md | 20 +++++++------------- 1 file changed, 7 insertions(+), 13 deletions(-) diff --git a/readme.md b/readme.md index 169bbe0d..37c85957 100644 --- a/readme.md +++ b/readme.md @@ -11,7 +11,7 @@ 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>) +- Weasyprint [dependencie](http://weasyprint.readthedocs.io/en/stable/install.html) Install Devicehub with *pip*: `pip3 install -U -r requirements.txt -e .` @@ -20,8 +20,8 @@ Create a PostgreSQL database called *devicehub* by running [create-db](examples/ - 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``. + 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`. @@ -45,28 +45,22 @@ $ 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`` +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: +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. +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`. +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`. From c2501a143a98dd58b41b097f4f85a4b5788b85b9 Mon Sep 17 00:00:00 2001 From: Santiago Lamora Date: Tue, 5 Apr 2022 13:20:26 +0200 Subject: [PATCH 09/10] Bump ereuse-utils from 0.4.0b49 to 0.4.0b50 --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 4dadabf0..56dbf2be 100644 --- a/requirements.txt +++ b/requirements.txt @@ -6,7 +6,7 @@ click==6.7 click-spinner==0.1.8 colorama==0.3.9 colour==0.1.5 -ereuse-utils[naming,test,session,cli]==0.4.0b49 +ereuse-utils[naming,test,session,cli]==0.4.0b50 Flask==1.0.2 Flask-Cors==3.0.10 Flask-Login==0.5.0 From 554d79d2f98978b8679f2b1cbc564ddbb6986d0f Mon Sep 17 00:00:00 2001 From: RubenPX Date: Wed, 6 Apr 2022 14:12:27 +0200 Subject: [PATCH 10/10] Upercase readme.md --- readme.md => README.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename readme.md => README.md (100%) diff --git a/readme.md b/README.md similarity index 100% rename from readme.md rename to README.md