diff --git a/README.md b/README.md new file mode 100644 index 00000000..37c85957 --- /dev/null +++ b/README.md @@ -0,0 +1,134 @@ +#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`. 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/development-setup.md b/development-setup.md new file mode 100755 index 00000000..c900574a --- /dev/null +++ b/development-setup.md @@ -0,0 +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 -y libpango1.0-0 libcairo2 libpq-dev` diff --git a/examples/app.py b/examples/app.py index da6e2202..415d86ce 100644 --- a/examples/app.py +++ b/examples/app.py @@ -20,5 +20,5 @@ app.register_blueprint(labels) # 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) 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',