This repository has been archived on 2024-05-31. You can view files and clone it, but cannot push or open issues or pull requests.
devicehub-teal/README.md

152 lines
4.3 KiB
Markdown
Raw Permalink Normal View History

2022-05-06 06:40:49 +00:00
# Devicehub
2022-04-04 10:34:33 +00:00
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/).
2022-04-04 15:59:51 +00:00
- Weasyprint [dependencie](http://weasyprint.readthedocs.io/en/stable/install.html)
2022-04-04 10:34:33 +00:00
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):
2022-04-04 15:59:51 +00:00
1. `sudo su - postgres`.
2. `bash examples/create-db.sh devicehub dhub`, and password `ereuse`.
2022-04-04 10:34:33 +00:00
- In MacOS: `bash examples/create-db.sh devicehub dhub`, and password `ereuse`.
2022-06-07 09:16:20 +00:00
Configure project using environment file (you can use provided example as quickstart):
2022-04-04 10:34:33 +00:00
```bash
$ cp examples/env.example .env
```
2022-06-07 09:16:20 +00:00
Using the `dh` tool for set up with one or multiple inventories.
2022-04-04 10:34:33 +00:00
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
```
2022-06-07 09:16:20 +00:00
The error bdist_wheel can happen when you work with a *virtual environment*.
2022-04-04 10:34:33 +00:00
To fix it, install in the *virtual environment* wheel
2022-04-04 15:59:51 +00:00
package. `pip3 install wheel`
2022-04-04 10:34:33 +00:00
## Multiple instances
2022-04-04 15:59:51 +00:00
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:
2022-04-04 10:34:33 +00:00
```bash
$ export dhi=dbtest; dh inv add --name dbtest
```
2022-04-04 15:59:51 +00:00
Note: The `dh` command is like `flask`, but it allows you to create and delete instances, and interface to them directly.
2022-04-04 10:34:33 +00:00
# Testing
1. `git clone` this project.
2022-04-04 15:59:51 +00:00
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`.
2022-04-04 10:34:33 +00:00
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 `<revision_id>_a_table_change`.
Edit the generated file with the necessary operations to perform the migration:
```bash
$ alembic edit <revision_id>
```
Apply migrations using:
```bash
$ alembic -x inventory=dbtest upgrade head
```
Then to go back to previous db version:
```bash
$ alembic -x inventory=dbtest downgrade <revision_id>
```
To see a full list of migrations use
```bash
$ alembic history
```
2022-06-07 09:16:20 +00:00
# Upgrade a deployment
2022-06-07 08:09:47 +00:00
For upgrade an instance of devicehub you need to do:
```bash
$ 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
```
2022-04-04 10:34:33 +00:00
## 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`.