|
||
---|---|---|
.github | ||
docs | ||
ereuse_devicehub | ||
examples | ||
scripts | ||
tests | ||
.babelrc.json | ||
.eslintignore | ||
.eslintrc.json | ||
.gitignore | ||
.pre-commit-config.yaml | ||
.prettierrc.json | ||
CHANGELOG.md | ||
CONTRIBUTING.md | ||
LICENSE.txt | ||
MANIFEST.in | ||
README.md | ||
alembic.ini | ||
development-setup.md | ||
licences.txt | ||
package.json | ||
pyproject.toml | ||
requirements-dev.txt | ||
requirements.txt | ||
setup.cfg | ||
setup.py | ||
tox.ini |
README.md
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 dependencie
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):
sudo su - postgres
.bash examples/create-db.sh devicehub dhub
, and passwordereuse
.
-
In MacOS:
bash examples/create-db.sh devicehub dhub
, and passwordereuse
.
Configure project using environment file (you can use provided example as quickstart):
$ 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:
$ export dhi=dbtest; dh inv add --common --name dbtest
Finally, run the app:
$ 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:
$ 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
git clone
this project.- Create a database for testing executing
create-db.sh
like the normal installation but changing the first parameter fromdevicehub
todh_test
:create-db.sh dh_test dhub
and passwordereuse
. - 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:
$ sudo su - postgres
$ bash $PATH_TO_DEVIHUBTEAL/examples/create-db.sh devicehub dhub
Initialize the database:
$ 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.
$ 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:
$ 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:
$ alembic edit <revision_id>
Apply migrations using:
$ alembic -x inventory=dbtest upgrade head
Then to go back to previous db version:
$ alembic -x inventory=dbtest downgrade <revision_id>
To see a full list of migrations use
$ alembic history
Upgrade a deployment
For upgrade an instance of devicehub you need to do:
$ cd $PATH_TO_DEVIHUBTEAL
$ source venv/bin/activate
$ git pull
$ alembic -x inventory=dbtest upgrade head
If all migrations pass successfully, then it is necessary restart the devicehub. Normaly you can use a little script for restart.
# sh gunicorn_api.sh
Generating the docs
git clone
this project.- Install plantuml. In Debian 9 is
# apt install plantuml
. - Execute
pip3 install -e .[docs]
in the project root folder. - Go to
<project root folder>/docs
and executemake 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
.