Formal changes to set up for 1.0a1
This commit is contained in:
Xavier Bustamante Talavera
parent
b0d8ca39fe
commit
9ad9e4a042
106
README.md
106
README.md
|
|
@ -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.
|
||||
|
||||
[](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 `<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`.
|
||||
100
README.rst
Normal file
100
README.rst
Normal file
|
|
@ -0,0 +1,100 @@
|
|||
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 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 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 <http://flask.pocoo.org/docs/1.0/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 ``<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``.
|
||||
|
|
@ -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/
|
||||
|
||||
<VirtualHost *:80>
|
||||
ServerName ${servername}
|
||||
|
|
|
|||
|
|
@ -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
|
||||
16
setup.py
16
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',
|
||||
|
|
|
|||
Reference in a new issue