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`.