The B2SHARE Docker image can be used as is and is available on Docker Hub as eudatb2share/b2share. However, a full B2SHARE installation requires many different services (e.g. elasticsearch, postgresql, redis, rabbitmq), thus we provide a standard deployment procedure that creates a demonstration environment. The next steps will describe how to use this deployment.
First clone the dockerize repository:
$ git clone https://github.com/EUDAT-B2SHARE/dockerize.git
B2SHARE requires B2ACCESS for user management. For this purpose you must create
a new B2ACCESS OAuth client, providing as the 'return URL' the address of the
local B2SHARE server and the authorization path:
https://$FQDN/api/oauth/authorized/b2access/
(where $FQDN must be replaced
with the domain of the B2SHARE server).
After successfully registering the B2ACCESS account please set the following environment variables with the username and password provided for the B2ACCESS account:
$ export B2ACCESS_CONSUMER_KEY=... # the username used for registration
$ export B2ACCESS_SECRET_KEY=... # the password used for registration
For demonstration purposes it's recommended to use the staging B2ACCESS
server. In this case make sure to define and export the
USE_STAGING_B2ACCESS
variable:
$ export USE_STAGING_B2ACCESS=1
The B2SHARE_SECRET_KEY environment variable (a secret string used for encrypting user sessions) must also be set as an environment variable. It is recommended to use a randomly generated string for this purpose. E.g.:
$ export B2SHARE_SECRET_KEY=mfTpGpQBwTTOmWCoZrYSuiJ1UzXq1d2L
B2SHARE needs connection to a list of external services: redis, elasticsearch,
a database (postgresql or mysql), and rabbitmq. To simplify the creation of
this necessary execution environment, the Docker application engine is used.
The default Docker configuration for B2SHARE will try to mount a folder from
the host machine. This host directory is designated by the environment
variable $B2SHARE_DATADIR
which should be an absolute path. This folder
is used to store all the data uploaded into B2SHARE and is therefore very
important.
B2SHARE has a set of configuration parameters, which should be inspected and
changed when necessary by the site administrator. On the first run of the
service, a configuration file will be created in the B2SHARE data location
(which also by default is mounted to the host folder
${B2SHARE_DATADIR}/b2share-data/
as described above). The name of this
configuration file is b2share.cfg
. Please note that after each update of
this file the service needs to be restarted
(with e.g.``docker-compose restart``) for the changes to take effect.
By default, the B2SHARE service will use a newly created postgresql database.
This database's data is persisted in ${B2SHARE_DATADIR}/postgresql-data/
.
In case you want to use an external database, one can be configured
by editing the b2share.cfg
file and defining the
SQLALCHEMY_DATABASE_URI
variable. For example, for a postresql database,
use SQLALCHEMY_DATABASE_URI =
"postgresql://db_username:db_password@db_host/db_name"
)
Note that you also need to remove the B2SHARE_SQLALCHEMY_DATABASE_URI
variable in the docker-compose.yml
file.
B2SHARE uses nginx as the front-end HTTP server, responsible for establishing
secure connections with clients over https. By default an autogenerated
security certificate is used, which triggers security warnings in the client
browsers. For a production server it is recommended to use a
valid certificate. To use it with nginx, place the certificate files in an
empty folder on the host machine (e.g. /b2share-etc/ssl
) and mount the
folder in the nginx container by updating the volumes
declaration in the
docker-compose.yml
file. Make sure that the following files are present in
the mounted folder:
ssl_certificate /b2share-etc/ssl/b2share.crt
ssl_certificate_key /b2share-etc/ssl/b2share.key
After all the configuration parameters have been set go into the recently
downloaded dockerize
folder and run docker-compose
, e.g.:
$ cd dockerize
## mandatory environment variables
$ export B2ACCESS_CONSUMER_KEY=... # the username used for registration
$ export B2ACCESS_SECRET_KEY=... # the password used for registration
$ export B2SHARE_SECRET_KEY=... # a secret string used for encrypting user sessions
$ export B2SHARE_JSONSCHEMAS_HOST='<FQDN>' # replace <FQDN> with the domain of the B2SHARE server
$ export B2SHARE_POSTGRESQL_DBNAME=... # name of the postgresql database used by b2share
$ export B2SHARE_POSTGRESQL_PASSWORD=... # password used by b2share when accessing the postgresql database
$ export B2SHARE_POSTGRESQL_USER=... # username used by b2share when accessing the postgresql database (default=b2share)
$ export B2SHARE_RABBITMQ_USER=... # username used by b2share when accessing RabbitMQ service
$ export B2SHARE_RABBITMQ_PASS=... # password used by b2share when accessing RabbitMQ service
$ export B2SHARE_DATADIR='<PATH>' # path on the host which will be mounted and contain all b2share related data, including postgresql, elasticsearch, redis, rabbitmq, nginx and b2share itself.
## optional environment variables
$ export USE_STAGING_B2ACCESS=1 # to run with staging (testing) b2access (unity install)
$ export INIT_DB_AND_INDEX=1 # when run the first time, initialize the database and indices
$ export LOAD_DEMO_COMMUNITIES_AND_RECORDS=1 # when run the first time, load some communities and records for demonstration
## run it
$ docker-compose up -d
After the docker image is built and running, B2SHARE will be available at https://<FQDN>. If B2SHARE does not become available, you can try inspecting the container logs to find the cause:
$ docker-compose logs -f b2share
The services can be stopped just like any other docker-compose deployment.
$ docker-compose down
This command will stop and remove all containers. The data will still be
available in the directory pointed by $B2SHARE_DATADIR
.
The services can be started as before. If the directory pointed by the
environment variable $B2SHARE_DATADIR
already contains data from
a previous run, the data will be reused. See section 1.7 for removing
all previously persisted data if you want to start from scratch.
$ docker-compose up -d
In order to remove all persisted data one can just delete the directory pointed
by $B2SHARE_DATADIR
. All containers must be stopped before removing the
directory.
Remember to also delete the containers.
The provided docker-compose file is not production ready. The
database has no backup mechanism running. The system administrator can
comment the "postgres" service and set the SQLALCHEMY_DATABASE_URI
as
described in section 1.3. It is also possible to enhance the postgresql
container by building a custom one.
By default files uploaded by users are written in
${B2SHARE_DATADIR}/b2share-data/files
. This location must be backuped or
written on a safe filesystem.
If the containers need to run on different servers it is recommended to use native docker volumes instead of mounted host directories.
The records metadata in your local instance of B2SHARE can be harvested by
various other repositories by using the included endpoint for the OAI-PMH
protocol. For the records to be visible in B2FIND, please create a ticket in
the B2FIND support queue (https://eudat.eu/support-
request?service=B2FIND
), by describing your instance and specifying the
OAI-PMH url (http://<FQDN>/oai2d
)
Before installing B2Share you will need the following software:
python3
virtualenv
andvirtualenvwrapper
$ # on OSX, with brew:
$ brew install python --framework --universal
$ pip install virtualenv virtualenvwrapper
docker
anddocker-compose
On macOS we recommend using Docker for Mac.
If the conditions are satisfied, open one terminal window and download in a
temporary folder the devenv/docker-compose
and devenv/run_demo.sh
files:
$ mdir develop-b2share
$ cd develop-b2share
$ curl -O https://raw.githubusercontent.com/EUDAT-B2SHARE/b2share/master/devenv/docker-compose.yml
$ curl -O https://raw.githubusercontent.com/EUDAT-B2SHARE/b2share/master/devenv/run_demo.sh
Then start the run_demo.sh
script:
$ chmod +x ./run_demo.sh
$ ./run_demo.sh
The script will create a python virtualenv, clone the master branch of B2SHARE into it, install the necessary python packages, build the web UI and start the Flask server in development mode. B2SHARE should be available at http://localhost:5000.
Please note that a custom B2ACCESS configuration is also needed, as described
above. The 'return URL' of the B2ACCESS configuration in this case can be set
to http://localhost:5000/api/oauth/authorized/b2access/
If working on the web UI, see also: https://github.com/EUDAT-B2SHARE/b2share/wiki/Developer's-corner.