Installation instructions

Preparation

Clone the repository to run the prerequisites:

$ git clone https://github.com/NSLS-II/sirepo-bluesky.git
$ cd sirepo-bluesky/

Starting Sirepo

To make use of the package, we need to run Sirepo as a service. We run Sirepo using Docker images (Podman can be used as well) from DockerHub. We can start Sirepo locally using the convenience script:

$ bash scripts/start_sirepo.sh -it

which runs a Docker container as

#!/bin/bash

# set -vxeuo pipefail
set -e

error_msg="Specify '-it' or '-d' on the command line as a first argument."

arg="${1:-}"

if [ -z "${arg}" ]; then
    echo "${error_msg}"
    exit 1
elif [ "${arg}" != "-it" -a "${arg}" != "-d" ]; then
    echo "${error_msg} Specified argument: ${arg}"
    exit 2
fi

if [ "${arg}" == "-it" ]; then
    remove_container="--rm"
else
    remove_container=""
fi

SIREPO_SRDB_HOST="${SIREPO_SRDB_HOST:-}"
SIREPO_SRDB_HOST_RO="${SIREPO_SRDB_HOST_RO:-}"
SIREPO_SRDB_GUEST="${SIREPO_SRDB_GUEST:-}"
SIREPO_SRDB_ROOT="${SIREPO_SRDB_ROOT:-'/sirepo'}"

unset cmd _cmd docker_image SIREPO_DOCKER_CONTAINER_ID

year=$(date +"%Y")
month=$(date +"%m")
day=$(date +"%d")

today="${HOME}/tmp/data/${year}/${month}/${day}"

if [ -d "${today}" ]; then
    echo "Directory ${today} exists."
else
    echo "Creating Directory ${today}"
    mkdir -p "${today}"
fi

docker_image_tag=${DOCKER_IMAGE_TAG:-'beta'}  # '20220806.215448' for the older tag
docker_image="radiasoft/sirepo:${docker_image_tag}"
docker_binary=${DOCKER_BINARY:-"docker"}

${docker_binary} pull ${docker_image}

${docker_binary} images

in_docker_cmd=$(cat <<EOF
mkdir -v -p ${SIREPO_SRDB_ROOT} && \
if [ ! -f "${SIREPO_SRDB_ROOT}/auth.db" ]; then \
    cp -Rv /SIREPO_SRDB_ROOT/* ${SIREPO_SRDB_ROOT}/; \
else \
    echo 'The directory exists. Nothing to do'; \
fi && \
sed -i -E \"s;export SIREPO_SRDB_ROOT=\"\(.*\)\";export SIREPO_SRDB_ROOT=\"$SIREPO_SRDB_ROOT\";g\" ~/.radia-run/start && \
cat ~/.radia-run/start && \
~/.radia-run/start
EOF
)

if [ -z "${SIREPO_SRDB_HOST_RO}" ]; then
    if [ -d "$PWD/sirepo_bluesky/tests/SIREPO_SRDB_ROOT" ]; then
        SIREPO_SRDB_HOST_RO="$PWD/sirepo_bluesky/tests/SIREPO_SRDB_ROOT"
    else
        echo "Cannot determine the location of the host SIREPO_SRDB_ROOT dir."
        exit 1
    fi
fi

echo "SIREPO_SRDB_HOST_RO=${SIREPO_SRDB_HOST_RO}"

cmd_start="${docker_binary} run ${arg} --init ${remove_container} --name sirepo \
    -e SIREPO_AUTH_METHODS=bluesky:guest \
    -e SIREPO_AUTH_BLUESKY_SECRET=bluesky \
    -e SIREPO_SRDB_ROOT=${SIREPO_SRDB_ROOT} \
    -e SIREPO_COOKIE_IS_SECURE=false \
    -e SIREPO_FEATURE_CONFIG_REACT_SIM_TYPES='' \
    -p 8000:8000 \
    -v $SIREPO_SRDB_HOST_RO:/SIREPO_SRDB_ROOT:ro,z "

cmd_extra=""
if [ ! -z "${SIREPO_SRDB_HOST}" -a ! -z "${SIREPO_SRDB_GUEST}" ]; then
    cmd_extra="-v ${SIREPO_SRDB_HOST}:${SIREPO_SRDB_GUEST}:rw,z "
fi

cmd_end="${docker_image} bash -l -c \"${in_docker_cmd}\""

cmd="${cmd_start}${cmd_extra}${cmd_end}"

echo -e "Command to run:\n\n${cmd}\n"
if [ "${arg}" == "-d" ]; then
    SIREPO_DOCKER_CONTAINER_ID=$(eval ${cmd})
    export SIREPO_DOCKER_CONTAINER_ID
    echo "Container ID: ${SIREPO_DOCKER_CONTAINER_ID}"
    ${docker_binary} ps -a
    ${docker_binary} logs ${SIREPO_DOCKER_CONTAINER_ID}
else
    eval ${cmd}
fi

Note

One can use the -d option instead of -it to run the container in the daemon mode.

Starting Mongo

Accessing the simualted data using Databroker requires us to have Mongo running. We can similarly run:

$ bash scripts/start_mongo.sh -it

or more explicitly

#!/bin/bash

set -vxeuo pipefail

error_msg="Specify '-it' or '-d' on the command line as a first argument."

arg="${1:-}"

if [ -z "${arg}" ]; then
    echo "${error_msg}"
    exit 1
elif [ "${arg}" != "-it" -a "${arg}" != "-d" ]; then
    echo "${error_msg} Specified argument: ${arg}"
    exit 2
fi

docker_image="mongo"
docker_binary=${DOCKER_BINARY:-"docker"}

${docker_binary} pull ${docker_image}
${docker_binary} images
${docker_binary} run ${arg} --rm -p 27017:27017 --name mongo ${docker_image}

Likewise, the -d option can be used instead of -it to run the container in the daemon mode.

Configuration of databroker

To to access the collected data with the databroker library, we need to configure it. For that, please copy the local.yml configuration file to the ~/.config/databroker/ directory if using macOS or Linux. For Windows systems, copy the configuration file to the %APPDATA%\databroker directory.

description: 'local databroker store'
metadatastore:
  module: 'databroker.headersource.mongo'
  class: 'MDS'
  config:
    host: 'localhost'
    port: 27017
    database: 'some_example_database'
    timezone: 'US/Eastern'
assets:
  module: 'databroker.assets.mongo'
  class: 'Registry'
  config:
    host: 'localhost'
    port: 27017
    database: 'some_example_database'

Installation

Note

The installation requires the srwpy and shadow3 simulation packages to be installed to make use of all features of the library. Those packages are primarily used by the corresponding handlers to be able to load the data from the package-specific formats. The packages are installed automatically when the sirepo-bluesky package is installed via pip:

• https://pypi.org/project/srwpy

• https://pypi.org/project/shadow3

One can also install the packages using conda from the conda-forge channel:

• https://anaconda.org/conda-forge/srwpy

• https://anaconda.org/conda-forge/shadow3

Start with creating a conda environment. If you do not have conda installation, one of the packages from https://github.com/conda-forge/miniforge can be used to quickly install the appropriate conda infrastructure.

At the command line:

$ conda create -n sirepo-bluesky -c conda-forge -y python=3.10
$ conda activate sirepo-bluesky

Then, to install the released version, run one of the following commands:

$ python3 -m pip install sirepo-bluesky        # to install from PyPI, OR
$ conda install -c conda-forge sirepo-bluesky  # to install from conda-forge

If you would like to run examples, it is recommended to use the development mode installation:

$ git clone https://github.com/NSLS-II/sirepo-bluesky.git
$ cd sirepo-bluesky/
$ python3 -m pip install -ve .

If you wish to run pytest tests or build the documentation, please install the development requirements, such as:

$ python3 -m pip install -r requirements-dev.txt

Note

You may need to install the Pandoc library. Please follow the instructions at https://pandoc.org/installing.html to install it.

Run tests

$ pytest -vv -s -x --pdb

Build documentation

$ make -C docs/ html