felicity-lims/README.md

# FELICITY LIMS

![Screenshot1](https://user-images.githubusercontent.com/17094364/137630249-b84e5b1c-f525-4b0a-8d1e-1e2820910a5f.png)

The next generation open source laboratory information management system for clinical/medical laboratories.

## Description

The Felicity LIMS project aims to create a Laboratory Information Management System (LIMS) that tracks the complete
laboratory workflow providing all the functionalities of a Laboratory Information Management System.

Felicity strives to promote an accurate flow of sample and associated experimental data to and through a laboratory to
produce information that is used to make conclusions and critical decisions.

Felicity LIMS will ensure that sufficient metadata is captured and clinical laboratory personnel can track the lifecycle
of a bio-specimen in the laboratory from receipt to dispatch.

Felicity is the quality of being good, pleasant, or desirable.

### FrontEnd

Felicity's frontend is developed using Vite, Vue, URQL, and Tailwind CS, etc.

### Backend

Felicity's backend is developed using FastAPI, Strawberry-Graphql and SQLAlchemy

Minio is used as object storage to store pdf reports

Mongodb is used to store audit logs

Postgres is the main db with core tables

Dragonfly is the redis cache to keep track of sample status locks, websocket subscriptions etc

## Main Features

- Dashboard - Analytics
- Patient - Listing, compact, detail, search, Audit Log
- Sample - Listing, Detail, Audit Log, Reports, search
- Worksheet - Templates, listing, auto create, multi create, manual create
- Inventory - Item manager, listing, detail, transactions, adjustments, orders, requests
- Shipment - Fhir ready (experimental), Listing, detail,
- Storage - store rooms, locations, containers, templates,
- Client - listing, detail, contacts
- User - listing, profiles, RBAC
- Billing - listing, profiles, RBAC -- incomplete
- Admin - admin functions
- Reflex rules

## Installation

Our recommended method to get up and running quickly is to use the docker.
This method uses Docker and docker compose which handles the details of installing dependencies for you.

We provide 2 methods to run felicity with docker. Choose whichever methods suits you best.

```shell
git clone https://github.com/beak-insights/felicity-lims.git
cd felicity-lims
```

##### Method 1. FastAPI serve static files generated by the vue frontend.

Docker service presets are: *felicity-aio-caddy*, *felicity-aio-nginx*, *felicity-aio*

- **felicity-aio-caddy** - felicity serves static files with caddy as a reverse proxy in front
- **felicity-aio-nginx** - felicity serves static files with nginx as a reverse proxy in front
- **felicity-aio** - felicity serves static files without a reverse proxy

```commandline
docker compose -f ./docker-compose.prod.yml up -d your_preset --build
docker compose -f docker-compose.prod.yml exec your_preset bash -c "cd felicity && alembic upgrade head"
docker compose -f docker-compose.prod.yml logs your_preset -f -n100
```

##### Method 2. Nginx/Caddy serve static files generated by the vue frontend.

Docker service presets are: *felicity-static-nginx*, *felicity-static-caddy*

- **felicity-static-nginx** - felicity handles the api and nginx serves static files
- **felicity-static-caddy** - felicity handles the api and caddy serves static files

```commandline
docker compose -f ./docker-compose.prod.yml up -d your_preset --build
docker compose -f docker-compose.prod.yml exec your_preset bash -c "cd felicity && alembic upgrade head"
docker compose -f docker-compose.prod.yml logs your_preset -f -n100
```

##### Alternative deployment method without docker

If you don't want to use docker, as an alternative we recommend supervisor.

```shell
# install os requirements
sudo apt update && apt install libcairo2-dev pkg-config python3-dev gcc g++

# create and activate a python virtual environment - we recomment using miniconda
conda create -n felicity python=3.11
conda activate felicity

# install felicity lims requirements
pip install -r requirements.txt;

# setup postgres - First create a database and user 
pnpm db:al:upgrade;

# install webapp dependencies using pnpm - we recommend node v18 +
pnpm i;

# build webapp and setup felicity to serve the static files
pnpm standalone:build

# gunicorn run felicity - Yay you are up and running
pnpm server:gu

# Demonising felicity-lims with supervisor

# Install supervisor
sudo apt install supervisor
    
# check status:
sudo systemctl status supervisor
    
# open supervisor config file:
sudo nano /etc/supervisor/conf.d/felicity_lims.conf
    
# Copy and Paste the following and edit correct accordingly
# command first argument must the python in your virtual environment
# command second argument must the felicity folder inside felicity_lims
[program:felicity_lims]
command=/home/<user>/miniconda3/bin/python <full path to felicity lims root folder>
autostart=true
autorestart=true
stderr_logfile=/var/log/felicity_lims.err.log
stdout_logfile=/var/log/felicity_lims.out.log

# command example could be like:
# command=/home/administrator/miniconda3/bin/python /home/administrator/felicity_lims/felicity

# inform supervisor of our new programs:
sudo supervisorctl reread
    
# tell supervisor to enact any changes:
sudo supervisorctl update
     
##### Supervisor management commands
# check program status:
sudo supervisorctl status
    
# reload 
sudo supervisorctl reload

# reload or restart felicity_lims:
sudo supervisorctl restart felicity_lims

# tail error logs:
sudo supervisorctl tail -f felicity_lims stderr  # or
tail -f /var/log/felicity_lims.err.log
    
# tail output logs:
sudo supervisorctl tail -f felicity_lims stdout  # or
tail -f /var/log/felicity_lims.out.log
```

## Application Monitoring

We have added open telemetry so that you can monitor how the application if performing. Make sure open tracing is
enabled if you want to collect metrics - `RUN_OPEN_TRACING=True` and also
run `opentelemetry-bootstrap --action=install`.

```shell
# Install signoz with docker method - easier method
git clone -b main https://github.com/SigNoz/signoz.git
cd signoz/deploy/

# Remove the Sample Application from SigNoz Dashboard
# open Docker Compose file deploy/docker/clickhouse-setup/docker-compose.yaml in a plain-text editor.
# Comment out or remove the services.hotrod and services.load-hotrod sections
docker compose -f docker/clickhouse-setup/docker-compose.yaml up -d

## When you are done installing SigNoz, you can access the UI at: http://localhost:3301
```

## Load testing

Use locust or any method and tell us how it performs. We have done our locust tests and we are extremely happy so far.

## Contact

- [EMail](mailto:aurthurmusendame@gmail.com?subject=[GitHub]%20Felicity%20Lims%20Enquiry)
- [LinkedIn](https://www.linkedin.com/in/aurthurmusendame)
- [Whatsapp](https://api.WhatsApp.com/send?phone=263776406399)
- [Telegram](https://www.t.me/aurthurm)