Beorum

Beorum OpenAPI spec

Beorum API defined in form of OpenAPI specification

see: https://swagger.io/specification/

running spec inside Swagger Editor

• you need docker on your machine
• git clone this repo to your local machine
• cd into cloned repo folder
• run spec viewer via:

  make swagger-editor
  

Preparation of development environment

1. Make sure you have Docker installed.
2. Make sure you have pyenv installed. Recipe is here.

docker

• Install on Ubuntu Linux
• Install on Windows
  • Install Oracle Virtual Box
  • Create Ubuntu VM
  • Install docker inside that machine

run

inside Docker

From main folder of repository:

make d-run

• Open http://localhost:3004/docs to view beorum in your browser.
• Backend API available at http://localhost:8084/docs.

without Docker

From main folder of repository (start backend):

make b-run

From main folder of repository (start frontend, use second shell):

make f-run

Database handling

Database is stored inside Postgres container named db.

• inside docker network beorum it is visible at db:5432
• outside, at host machine it is available via localhost:5430

Since it is inside container, when you cleanup via make d-stop or make d-clean or this is your first run of server then you need to recreate DB before starting server, so:

• make db-create
• make d-run

CAUTION: remember to fill POSTGRES_PASSWORD inside .env and .env.localdev before starting db-create or d-run. Otherwise, docker compose can't properly initialize Postgres container and reports with:

db_1        | Error: Database is uninitialized and superuser password is not specified.
db_1        |        You must specify POSTGRES_PASSWORD to a non-empty value for the
db_1        |        superuser. For example, "-e POSTGRES_PASSWORD=password" on "docker run".
db_1        | 
db_1        |        You may also use "POSTGRES_HOST_AUTH_METHOD=trust" to allow all
db_1        |        connections without a password. This is *not* recommended.

standalone DB

You may want just to start database inside container f.ex. to debug code with Pycharm. Do it via make db-up-d

database schema change

When you want to change database schema/model follow this steps:

1. Modify schema at backend/src/app/db/models.py
2. Regenerate migrations: make db-make-migrations
3. Apply migration: make db-create and check that it works
4. Commit new migration file from backend/migrations/models/

database viewer

You may use DBeaver:

• https://dbeaver.io/download/
• https://github.com/dbeaver/dbeaver/wiki/Installation
• https://linux.how2shout.com/3-ways-to-install-dbeaver-ubuntu-22-04-lts-jammy-linux/#5_Install_Dbeaver_using_Snap

Usage:

• https://github.com/dbeaver/dbeaver/wiki/Application-Window-Overview
• https://github.com/dbeaver/dbeaver/wiki/Create-Connection
• https://github.com/dbeaver/dbeaver/wiki/Database-Navigator
• https://github.com/dbeaver/dbeaver/wiki/ER-Diagrams