From 9ad9e4a0429fc22a2a1fd3f8454fcdd9f7484360 Mon Sep 17 00:00:00 2001 From: Xavier Bustamante Talavera Date: Sat, 15 Jun 2019 15:08:08 +0200 Subject: [PATCH] Formal changes to set up for 1.0a1 --- README.md | 106 ------------------------------------------- README.rst | 100 ++++++++++++++++++++++++++++++++++++++++ examples/apache.conf | 8 ++-- examples/wsgi.wsgi | 23 ---------- setup.py | 16 +++---- 5 files changed, 111 insertions(+), 142 deletions(-) delete mode 100644 README.md create mode 100644 README.rst delete mode 100644 examples/wsgi.wsgi diff --git a/README.md b/README.md deleted file mode 100644 index a02b5a04..00000000 --- a/README.md +++ /dev/null @@ -1,106 +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). - -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/ereuse/teal) and -[Flask](http://flask.pocoo.org). - -## Installing -The requirements are: - -- Python 3.5.3 or higher. In debian 9 is `# apt install python3-pip`. -- [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 ereuse-devicehub -U --pre`. - -## Running -Download, or copy the contents, of [this file](examples/app.py), and -call the new file ``app.py``. - -Create a PostgreSQL database called *devicehub* by running -[create-db](examples/create-db.sh): - -- In a Debian 9 bash terminal, execute the following two commands: - 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`. - -Create the tables in the database by executing in the same directory -where `app.py` is: - -```bash -$ flask init-db -``` - -Finally, run the app: - -```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`. - -See the [Flask quickstart](http://flask.pocoo.org/docs/1.0/quickstart/) -for more info. - -The error 'bdist_wheel' can happen when you works with *virtual environment*. -To fix it, install in the *virtual environment* wheel package. `pip3 install wheel` - -## Administrating -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 -available commands by just executing ``flask`` and get more information -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) - -## Testing -To run the tests you will need to: - -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`. - -## 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. -3. 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.rst b/README.rst new file mode 100644 index 00000000..83c9b65b --- /dev/null +++ b/README.rst @@ -0,0 +1,100 @@ +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 ereuse-devicehub -U --pre``. + +Running +******* +Download, or copy the contents, of `this file `__, and +call the new file ``app.py``. + +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``. + +Create the tables in the database by executing in the same directory +where ``app.py`` is: + +.. code:: bash + + $ flask init-db + +Finally, run the app: + +.. code:: 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``. + +Execute ``flask`` only to know all the administration options Devicehub +offers. + +See the `Flask +quickstart `__ for more +info. + +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 execute +one instance, use the ``flask`` command, to execute multiple instances +use the ``dh`` command. 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``. + +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/examples/apache.conf b/examples/apache.conf index e016422c..6bf4b017 100644 --- a/examples/apache.conf +++ b/examples/apache.conf @@ -2,14 +2,14 @@ # It uses plain HTTP # Change the following variables: -Define servername api.devicetag.io # The domain used to access the server -Define appdir /home/devicetag/sites/${servername}/source/ +Define servername api.devicetag.io # The path where the app directory is. Apache must have access to this folder. -Define wsgipath ${appdir}/wsgi.py +Define appdir /home/ereuse/sites/${servername}/source/ # The location of the .wsgi file -Define pyvenv ${appdir}../venv/ +Define wsgipath ${appdir}/wsgi.py # The path where the virtual environment is (the folder containing bin/activate) +Define pyvenv ${appdir}../venv/ ServerName ${servername} diff --git a/examples/wsgi.wsgi b/examples/wsgi.wsgi deleted file mode 100644 index c9c1722d..00000000 --- a/examples/wsgi.wsgi +++ /dev/null @@ -1,23 +0,0 @@ -""" -An exemplifying Apache python WSGI to a Devicehub app. - -Based in http://flask.pocoo.org/docs/0.12/deploying/mod_wsgi/ - -You only need to modify ``app_dir``. -""" - -from pathlib import Path - -import sys - -app_dir = Path(__file__).parent -"""The **directory** where app.py is located. Change this accordingly.""" - -assert app_dir.is_dir(), 'app_dir must point to a directory: {}'.format(app_dir) -app_dir = str(app_dir.resolve()) - -# Load the app -# ------------ -sys.path.insert(0, str(app_dir)) -# noinspection PyUnresolvedReferences -from app import app as application diff --git a/setup.py b/setup.py index d49a9486..a4bb1e59 100644 --- a/setup.py +++ b/setup.py @@ -1,4 +1,3 @@ -from collections import OrderedDict from pathlib import Path from setuptools import find_packages, setup @@ -10,22 +9,21 @@ test_requires = [ setup( name='ereuse-devicehub', - version='0.2.0b3', + version='1.0a1', url='https://github.com/ereuse/devicehub-teal', - project_urls=OrderedDict(( - ('Documentation', 'http://devicheub.ereuse.org'), - ('Code', 'http://github.com/ereuse/devicehub-teal'), - ('Issue tracker', 'https://tree.taiga.io/project/ereuseorg-devicehub/issues?q=rules') - )), + project_urls={ + 'Documentation': 'http://devicheub.ereuse.org', + 'Code': 'http://github.com/ereuse/devicehub-teal', + 'Issue tracker': 'https://tree.taiga.io/project/ereuseorg-devicehub/issues?q=rules' + }, license='Affero', author='eReuse.org team', author_email='x.bustamante@ereuse.org', description='A system to manage devices focusing reuse.', packages=find_packages(), include_package_data=True, - python_requires='>=3.5.3', + python_requires='>=3.7.3', long_description=Path('README.md').read_text('utf8'), - long_description_content_type='text/markdown', install_requires=[ 'teal>=0.2.0a38', # teal always first 'click',