emhub 1.0.2
Web application for monitoring EM results


.. |logo_image| image:: https://github.com/3dem/emhub/wiki/images/emhub.png
   :height: 60px

.. |logo_text| image:: https://github.com/3dem/emhub/wiki/images/emhub-default-logo.svg
   :height: 60px

|logo_image| |logo_text|

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
------------------

.. code-block:: bash

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

    git clone https://github.com/3dem/emhub.git
    # OR
    git clone git@github.com: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:

.. code-block:: bash

    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.

.. code-block:: bash

    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.

.. code-block:: bash

    # 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.

.. code-block:: bash

    # 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"