Developer Documentation

Project structure and outline

The Bibbox docker system can mainly be divided into 3 parts:

• Front End

  • Angular Front End (Precompiled and mounted within the proxy container https://github.com/bibbox/sys-bibbox/tree/master/frontend)

• Back End

  • Flask Backend container (https://github.com/bibbox/sys-bibbox/tree/master/backend)
  • Celery Container (https://github.com/bibbox/sys-bibbox/tree/master/backend Celery and backend use the same Docker image)
  • Postgres DB (https://github.com/bibbox/sys-bibbox/blob/master/postgresql/Dockerfile)
  • Redis Data Store (Official Redis Docker image. Used by Celery as cache store)
  • Adminer (Official Docker image for DB debugging)
  • Celery Monitor (Celery container with Frotnend to debug asynchronous tasks)
  • cadvisor (Monitoring for the complete docker-compose bibbox chain)

• Apacheproxy (Main linking centerpoint https://github.com/bibbox/sys-bibbox/tree/master/apacheproxy)

To get an idea how this works in an easier fashion you can have a look at https://github.com/mrsan22/Angular-Flask-Docker-Skeleton, which served as base for the work done on the Bibbox docker framework. The nginx implementation was replaced by Apache since this offered a more convenient workflow.

Prequisites

The following applications need to be installed or are installed using the INSTALL.sh script:

• Docker and docker-compose
• nodejs, nvm (Node version manager) and npm (node package manager) (see INSTALL.sh for version details)
• Python 3.x (see requirements.txt in the repository for more information on python requirements)

Front-End Details

• The Frontend is angular based and uses the ngrx-store principle to achieve the desired functionality (https://ngrx.io/guide/store). Code Structure:

• Part I: Everything visible in the Frontend is a component uses functions defined in the ngrx store part.
  sys-bibbox/frontend/src
  ├── app
  │   ├── app.module.ts
  │   ├── app-routing.module.ts
  │   ├── commons.ts
  │   ├── components
  │   │   ├── about
  │   │   │   ├── contact
  │   │   │   │   ├── contact.component.html
  │   │   │   │   ├── contact.component.scss
  │   │   │   │   ├── contact.component.spec.ts
  │   │   │   │   └── contact.component.ts
  │   │   │   ├── imprint
  │   │   │   │   ├── imprint.component.html
  │   │   │   │   ├── imprint.component.scss
  │   │   │   │   ├── imprint.component.spec.ts
  │   │   │   │   └── imprint.component.ts
  │   │   │   └── partners
  │   │   │   ├── partners.component.html
  │   │   │   ├── partners.component.scss
  │   │   │   ├── partners.component.spec.ts
  │   │   │   └── partners.component.ts
  │   │   ├── activities
  │   │   │   ├── activities.component.html
  │   │   │   ├── activities.component.scss
  │   │   │   ├── activities.component.spec.ts
  │   │   │   ├── activities.component.ts
  │   │   │   └── activity-menu-overlay
  │   │   │   ├── activity-menu-overlay.component.html
  │   │   │   ├── activity-menu-overlay.component.scss
  │   │   │   ├── activity-menu-overlay.component.spec.ts
  │   │   │   └── activity-menu-overlay.component.ts
  │   │   ├── applications
  │   │   │   ├── application-group
  │   │   │   │   ├── application-group.component.html
  │   │   │   │   ├── application-group.component.scss
  │   │   │   │   ├── application-group.component.spec.ts
  │   │   │   │   ├── application-group.component.ts
  │   │   │   │   └── application-tile
  │   │   │   │   ├── application-tile.component.html
  │   │   │   │   ├── application-tile.component.scss
  │   │   │   │   ├── application-tile.component.spec.ts
  │   │   │   │   └── application-tile.component.ts
  │   │   │   ├── applications.component.html
  │   │   │   ├── applications.component.scss
  │   │   │   ├── applications.component.spec.ts
  │   │   │   ├── applications.component.ts
  │   │   │   ├── install-screen
  │   │   │   │   ├── install-screen.component.html
  │   │   │   │   ├── install-screen.component.scss
  │   │   │   │   ├── install-screen.component.spec.ts
  │   │   │   │   └── install-screen.component.ts
  │   │   │   └── install-screen-dialog
  │   │   │   ├── install-screen-dialog.component.html
  │   │   │   ├── install-screen-dialog.component.scss
  │   │   │   ├── install-screen-dialog.component.spec.ts
  │   │   │   └── install-screen-dialog.component.ts
  │   │   ├── app-scaffold
  │   │   │   ├── app.component.html
  │   │   │   ├── app.component.scss
  │   │   │   ├── app.component.spec.ts
  │   │   │   ├── app.component.ts
  │   │   │   ├── footer
  │   │   │   │   ├── footer.component.html
  │   │   │   │   ├── footer.component.scss
  │   │   │   │   ├── footer.component.spec.ts
  │   │   │   │   └── footer.component.ts
  │   │   │   └── header
  │   │   │   ├── header.component.html
  │   │   │   ├── header.component.scss
  │   │   │   ├── header.component.spec.ts
  │   │   │   └── header.component.ts
  │   │   ├── instances
  │   │   │   ├── instance-detail-page
  │   │   │   │   ├── instance-detail-page.component.html
  │   │   │   │   ├── instance-detail-page.component.scss
  │   │   │   │   ├── instance-detail-page.component.spec.ts
  │   │   │   │   └── instance-detail-page.component.ts
  │   │   │   ├── instances.component.html
  │   │   │   ├── instances.component.scss
  │   │   │   ├── instances.component.spec.ts
  │   │   │   ├── instances.component.ts
  │   │   │   └── instance-tile
  │   │   │   ├── instance-tile.component.html
  │   │   │   ├── instance-tile.component.scss
  │   │   │   ├── instance-tile.component.spec.ts
  │   │   │   └── instance-tile.component.ts
  │   │   ├── login TODO
  │   │   │   ├── login.component.html
  │   │   │   ├── login.component.scss
  │   │   │   ├── login.component.spec.ts
  │   │   │   └── login.component.ts
  │   │   ├── not-found
  │   │   │   ├── not-found.component.html
  │   │   │   ├── not-found.component.scss
  │   │   │   ├── not-found.component.spec.ts
  │   │   │   └── not-found.component.ts
  │   │   └── sys-logs
  │   │   ├── sys-logs.component.html
  │   │   ├── sys-logs.component.scss
  │   │   ├── sys-logs.component.spec.ts
  │   │   └── sys-logs.component.ts
  │   ├── httperror.interceptor.ts
  

• Part II: Store part implement all the actions, effects, models, reducers, selectors and services:
  │   └── store
  │   ├── actions
  │   │   ├── activity.actions.ts
  │   │   ├── applications.actions.ts
  │   │   └── instance.actions.ts
  │   ├── effects
  │   │   ├── activity.effects.ts
  │   │   ├── applications.effects.ts
  │   │   └── instance.effects.ts
  │   ├── models
  │   │   ├── activity.model.ts
  │   │   ├── application-group-item.model.ts
  │   │   ├── app-state.model.ts
  │   │   └── instance-item.model.ts
  │   ├── reducers
  │   │   ├── activity.reducer.ts
  │   │   ├── application-group.reducer.ts
  │   │   └── instance.reducer.ts
  │   ├── selectors
  │   │   ├── activity.selector.ts
  │   │   ├── application-group.selector.ts
  │   │   └── instance.selector.ts
  │   └── services
  │   ├── activity.service.spec.ts
  │   ├── activity.service.ts
  │   ├── application.service.spec.ts
  │   ├── application.service.ts
  │   ├── auth.service.spec.ts
  │   ├── auth.service.ts
  │   ├── instance.service.spec.ts
  │   ├── instance.service.ts
  │   ├── login.service.spec.ts
  │   ├── login.service.ts
  │   ├── socketio.service.spec.ts
  │   ├── socketio.service.ts
  │   ├── validator.service.spec.ts
  │   └── validator.service.ts
  ├── app.config.ts (created by Angular CLI)
  Note that this exactly resembels the structure given in the NGRx tutorial (https://ngrx.io/guide/store).
  

• Part III images and build environments
  ├── assets
  │   ├── announced.png
  │   ├── b3africa.png
  │   ├── bbmri-eric.png
  │   ├── close.png
  │   ├── done.png
  │   ├── error.png
  │   ├── external_ref.png
  │   ├── favicon.ico
  │   ├── furley_bg.png
  │   ├── loading.gif
  │   ├── loading_old.gif
  │   ├── lock.png
  │   ├── new.png
  │   ├── pawn_small.png
  │   ├── silicolab_logo.png
  │   ├── silicolab_logo_small.png
  │   ├── silicolab_logo.svg
  │   └── silicolab_logo_white.png
  ├── environments
  │   ├── environment.prod.ts
  │   ├── environment.prod.ts.template
  │   ├── environment.ts
  │   └── environment.ts.template
  
• Standart angular files mostly generated by the Angular CLI (edited in cases)
  ├── favicon.ico
  ├── index.html
  ├── main.ts
  ├── polyfills.ts
  ├── proxy.conf.json
  ├── styles.scss
  ├── styles-variables.scss
  └── test.ts
  

Front end TODO'S:

• Authentication for users;
  • See tutorial here https://mherman.org/blog/authentication-in-angular-with-ngrx/
• Styling

Back-End Details

The Backend code can be grouped the backend code regarding:

• api: Code implementing the Flask API calls it uses code defined in
  • the Bibbox Folder: Implements the file handling and data I/O providing the neccesary JSON data to the API calls.
• celery config files and tasks
• models contains the DB implementations for the database
  • services implements the SQL-Alchemy services consuming the models
• static features Api spec files in different formats
• util features constants and globals in a single script
• Other files cover init and configs for falsk and the neccesary interfaces

/opt/bibbox/sys-bibbox/backend/
├── app
* Part I: Main Code influencing Front end behaviour
│   ├── api
│   │   ├── activity.py
│   │   ├── apps.py
│   │   ├── authentication.py
│   │   ├── default.py
│   │   ├── __init__.py
│   │   └── instance.py
│   ├── bibbox
│   │   ├── app.py
│   │   ├── docker_handler.py
│   │   ├── file_handler.py
│   │   ├── __init__.py
│   │   ├── instance_controler.py
│   │   ├── instance_handler.py
│   │   └── instance.py
* Part II DB and asynchronous Tasks
│   ├── celeryconfig.py
│   ├── celerytasks
│   │   ├── __init__.py
│   │   └── tasks.py
│   ├── dirty_test_code.py
│   ├── __init__.py
│   ├── models
│   │   ├── activity.py
│   │   ├── app.py
│   │   ├── catalogue.py
│   │   ├── __init__.py
│   │   ├── log.py
│   │   └── user.py
│   ├── services
│   │   ├── activity_service.py
│   │   ├── app_service.py
│   │   ├── catalogue_service.py
│   │   ├── db_logger_service.py
│   │   ├── __init__.py
│   │   ├── log_service.py
│   │   ├── socketio_service.py
│   │   └── user_service.py
│   ├── static
│   │   ├── bibbox-api-spec old.yml
│   │   ├── bibbox-api-spec.yml
│   │   ├── main.html
│   │   └── swagger.json
│   ├── utility
│   │   ├── celery_util.py
│   │   └── __init__.py
│   └── utils
│   ├── common.py
│   └── __init__.py
* Part III: Init Stuff for websockets and Falsk + logs
├── celery_worker.py
├── debug-test.py
├── Dockerfile
├── entrypoint.sh
├── __init__.py
├── logs
│   ├── debug.log
│   ├── error.log
│   ├── info.log
│   └── warning.log
├── manage.py
├── requirements.txt
├── runflask.py
├── settings.py
├── uwsgi.ini
├── uwsgi_params
└── wsgi.py

Set up Front-End Developement environment

• Easiset way (Linux Debian based):
  

  • Install Bibbox locally under linux (See Install Bibbox)
  • Install VS-Code (Goto https://code.visualstudio.com/download)
  • Set up local DNS Service (See Install Bibbox)
  • Goto sys-bibbox/frontend
  • Type code . into bash
  • After VS Code opens type ng serve
  • Open the link the console shows you (If setup went correctly you should see a Bibbox interface without any errors)
  • Change any code file and watch it change live in your browser.

• NOTE: Prequesite is that the DNS service and Bibbox installation fully works