EMhub is a web application for data management at scientific core facilities, specially designed for operations of middle-size CryoEM centers. It allows the creation of users and resources (e.g. microscopes or other instruments). It also coordinates access to resources through applications and bookings, providing full traceability and reporting of usage.

Additionally, a REST API is exposed that permits the writing of external scripts to communicate with the application. This feature allows to write "workers" that can monitor new data collection sessions and handle different tasks such as data transfer or on-the-fly processing.

For more detailed information check the documentation at:

https://3dem.github.io/emdocs/emhub/

Development

Basic Installation

conda create --name=emhub python=3.8
conda activate emhub

git clone https://github.com/3dem/emhub.git
# OR
git clone [email protected]:3dem/emhub.git
cd emhub

# If you want to use the development branch, then do:
# git checkout devel

pip install -e .

# Generate some test data
emh-data --create_instance

export FLASK_APP=emhub
export EMHUB_INSTANCE=~/.emhub/instances/test

# Now launch the built-in Flask development server:
flask run --debug

# or with gunicorn:
gunicorn -k gevent --workers=2 'emhub:create_app()' --bind 0.0.0.0:5000

# Then launch a web browser at http://127.0.0.1:5000/
# user: admin, password: admin

Publishing the package to PyPI

In order to make the emhub available to install with pip install emhub, we need to:

python install twine restructuredtext-lint
cd emhub

# It might be a good idea to check the README.rst before uploading:
rst-lint README.rst

python setup.py sdist
twine upload dist/emhub-0.0.1a3.tar.gz

Creating a Docker image

A Dockerfile has been include to create Docker images.

cd emhub
docker build . -t emhub
docker run --rm -p 8080:8080 --name=emhub -v $PWD/instance:/instance

Upgrading Database model with Alembic

If we modify the database models, then an update/migration is required.

# Do changes in the model (data_models.py)

alembic revision --autogenerate

# Review the generated script

alembic upgrade head  # or use first the --sql option to see the commands

Generating Documentation with Sphinx

A Python environment with Sphinx and other dependencies is required to build the documentation.

# Install environment

conda create -y --name=emhub-docs python=3.8
conda activate emhub-docs
conda install nodejs=20 -c conda-forge -y
npm install -g jsdoc
pip install -e .  # install emhub
pip install -r docs/requirements.txt  # install doc requirements

# Build the docs

python build_docs.py

# or just
sphinx-build -b html docs/ html/

# Rsync the generated html files to the emdocs repo

rsync -av html/ ~/work/documentation/emdocs/emhub/
cd ../emhub-docs/
git ci -am "Updated html files"