invenio-app-ils

https://img.shields.io/travis/inveniosoftware/invenio-app-ils.svg https://img.shields.io/coveralls/inveniosoftware/invenio-app-ils.svg https://img.shields.io/github/license/inveniosoftware/invenio-app-ils.svg

Invenio App ILS

Further documentation is available on https://invenio_app_ils.readthedocs.io/

Installation

See INSTALL.rst

User’s Guide

This part of the documentation will show you how to get started in using invenio-app-ils.

Installation

First, create a virtualenv using virtualenvwrapper in order to sandbox our Python environment for development:

$ mkvirtualenv my-site

Start all dependent services using docker-compose (this will start PostgreSQL, Elasticsearch 6, RabbitMQ and Redis):

$ docker-compose up -d

Note

Make sure you have enough virtual memory for Elasticsearch in Docker:

# Linux
$ sysctl -w vm.max_map_count=262144

# macOS
$ screen ~/Library/Containers/com.docker.docker/Data/com.docker.driver.amd64-linux/tty
<enter>
linut00001:~# sysctl -w vm.max_map_count=262144

Next, bootstrap the instance (this will install all Python dependencies and build all static assets):

$ ./scripts/bootstrap

Next, create database tables, search indexes and message queues:

$ ./scripts/setup
Running

Start the webserver:

$ ./scripts/server

Start the a background worker:

$ celery worker -A invenio_app.celery -l INFO

Start a Python shell:

$ ./scripts/console
Upgrading

In order to upgrade an existing instance simply run:

$ ./scripts/update
Testing

Run the test suite via the provided script:

$ ./run-tests.sh

By default, end-to-end tests are skipped. You can include the E2E tests like this:

$ env E2E=yes ./run-tests.sh

For more information about end-to-end testing see pytest-invenio

Documentation

You can build the documentation with:

$ python setup.py build_sphinx
UI Development

The user interface is a standalone React application created using [create-react-app](https://facebook.github.io/create-react-app/). The easiest development setup consists in starting separately Invenio, for REST APIs, and the React app using the create-react-app webserver.

First of all, you have to create your own personal access token, to be able to GET or POST data to the API:

  • start the server:

    $ ./scripts/server

  • visit https://127.0.0.1:5000/account/settings/applications/, login as admin

  • create a personal access token

  • create a file .env.development in invenio_app_ils/ui/ and add the token:

    $ echo 'REACT_APP_JWT_TOKEN=<paste token here>' > ./invenio_app_ils/ui/.env.development

  • since the React app is server under a different port (normally, :3000), you need to change extra settings on Invenio to allow requests from different domains. In config.py, change the following:

    # CORS
# ====
# change this only while developing
CORS_SEND_WILDCARD = False
CORS_SUPPORTS_CREDENTIALS = True

You won’t need these changes in production because the token is automatically retrieved by the current logged in user and the React app will be served from the same domain.

Production environment

You can use simulate a full production environment using the docker-compose.full.yml. You can start it like this:

$ docker-compose -f docker-compose.full.yml up -d

In addition to the normal docker-compose.yml, this one will start:

  • HAProxy (load balancer)
  • Nginx (web frontend)
  • UWSGI (application container)
  • Celery (background task worker)
  • Flower (Celery monitoring)

Configuration

Default configuration for invenio-app-ils.

You overwrite and set instance-specific configuration by either:

  • Configuration file: <virtualenv prefix>/var/instance/invenio.cfg
  • Environment variables: APP_<variable name>
invenio_app_ils.config.ACCOUNTS_REST_READ_USERS_LIST_PERMISSION_FACTORY(*args, **kwargs)

Default list users permission factory: reject any request.

invenio_app_ils.config.ACCOUNTS_REST_READ_USER_PROPERTIES_PERMISSION_FACTORY(*args, **kwargs)

Default read user properties permission factory: reject any request.

invenio_app_ils.config.ACCOUNTS_REST_UPDATE_USER_PROPERTIES_PERMISSION_FACTORY(*args, **kwargs)

Default modify user properties permission factory: reject any request.

invenio_app_ils.config.ACCOUNTS_SESSION_REDIS_URL = 'redis://localhost:6379/1'

Redis session storage URL.

invenio_app_ils.config.APP_ALLOWED_HOSTS = ['localhost', '127.0.0.1']

Since HAProxy and Nginx route all requests no matter the host header provided, the allowed hosts variable is set to localhost. In production it should be set to the correct host and it is strongly recommended to only route correct hosts to the application.

invenio_app_ils.config.BABEL_DEFAULT_LANGUAGE = 'en'

Default language

invenio_app_ils.config.BABEL_DEFAULT_TIMEZONE = 'Europe/Zurich'

Default time zone

invenio_app_ils.config.BASE_TEMPLATE = 'invenio_theme/page.html'

Global base template.

invenio_app_ils.config.CELERY_BEAT_SCHEDULE = {'accounts': {'task': 'invenio_accounts.tasks.clean_session_table', 'schedule': datetime.timedelta(0, 3600)}, 'indexer': {'task': 'invenio_indexer.tasks.process_bulk_queue', 'schedule': datetime.timedelta(0, 300)}}

Scheduled tasks configuration (aka cronjobs).

invenio_app_ils.config.CELERY_BROKER_URL = 'amqp://guest:guest@localhost:5672/'

URL of message broker for Celery (default is RabbitMQ).

invenio_app_ils.config.CELERY_RESULT_BACKEND = 'redis://localhost:6379/2'

URL of backend for result storage (default is Redis).

invenio_app_ils.config.COLLECT_STORAGE = 'flask_collect.storage.file'

Static files collection method (defaults to copying files).

invenio_app_ils.config.COVER_TEMPLATE = 'invenio_theme/page_cover.html'

Cover page base template (used for e.g. login/sign-up).

invenio_app_ils.config.FOOTER_TEMPLATE = 'invenio_theme/footer.html'

Footer base template.

invenio_app_ils.config.HEADER_TEMPLATE = 'invenio_theme/header.html'

Header base template.

invenio_app_ils.config.I18N_LANGUAGES = []

Other supported languages (do not include the default language in list).

invenio_app_ils.config.ILS_VIEWS_PERMISSIONS_FACTORY(action)

Permissions factory for ILS views to handle all ILS actions.

invenio_app_ils.config.JSONSCHEMAS_HOST = '127.0.0.1:5000'

Hostname used in URLs for local JSONSchemas.

invenio_app_ils.config.MAIL_SUPPRESS_SEND = True

Disable email sending by default.

invenio_app_ils.config.MAX_CONTENT_LENGTH = 104857600

Max upload size for form data via application/mulitpart-formdata.

invenio_app_ils.config.RATELIMIT_STORAGE_URL = 'redis://localhost:6379/3'

Storage for ratelimiter.

invenio_app_ils.config.RECORDS_EDITOR_URL_PREFIX = '/editor'

Default URL we want to serve our editor application, i.e /editor.

invenio_app_ils.config.SECRET_KEY = 'CHANGE_ME'

Secret key - each installation (dev, production, …) needs a separate key. It should be changed before deploying.

invenio_app_ils.config.SECURITY_EMAIL_SENDER = 'info@inveniosoftware.org'

Email address used as sender of account registration emails.

invenio_app_ils.config.SECURITY_EMAIL_SUBJECT_REGISTER = 'Welcome to invenio-app-ils!'

Email subject for account registration emails.

Sets cookie with the secure flag by default

invenio_app_ils.config.SETTINGS_TEMPLATE = 'invenio_theme/page_settings.html'

Settings base template.

invenio_app_ils.config.SQLALCHEMY_DATABASE_URI = 'postgresql+psycopg2://test:psw@localhost/ils'

Database URI including user and password

invenio_app_ils.config.SUPPORT_EMAIL = 'info@inveniosoftware.org'

Email address for support.

Usage

invenio-app-ils.

API Reference

If you are looking for information on a specific function, class or method, this part of the documentation is for you.

API Docs

Views

Blueprint used for loading templates.

The sole purpose of this blueprint is to ensure that Invenio can find the templates and static files located in the folders of the same names next to this file.

invenio_app_ils.views.index(path=None)[source]

UI base view.

invenio_app_ils.views.ping()[source]

Ping blueprint used by loadbalancer.

Additional Notes

Notes on how to contribute, legal information and changes are here for the interested.

Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

Types of Contributions
Report Bugs

Report bugs at https://github.com/invenio_app_ils/invenio_app_ils/issues.

If you are reporting a bug, please include:

  • Your operating system name and version.
  • Any details about your local setup that might be helpful in troubleshooting.
  • Detailed steps to reproduce the bug.
Fix Bugs

Look through the GitHub issues for bugs. Anything tagged with “bug” is open to whoever wants to implement it.

Implement Features

Look through the GitHub issues for features. Anything tagged with “feature” is open to whoever wants to implement it.

Write Documentation

invenio-app-ils could always use more documentation, whether as part of the official invenio-app-ils docs, in docstrings, or even on the web in blog posts, articles, and such.

Submit Feedback

The best way to send feedback is to file an issue at https://github.com/invenio_app_ils/invenio_app_ils/issues.

If you are proposing a feature:

  • Explain in detail how it would work.
  • Keep the scope as narrow as possible, to make it easier to implement.
  • Remember that this is a volunteer-driven project, and that contributions are welcome :)
Get Started!

Ready to contribute? Here’s how to set up invenio_app_ils for local development.

  1. Fork the invenio_app_ils/invenio_app_ils repo on GitHub.

  2. Clone your fork locally:

    $ git clone git@github.com:your_name_here/invenio_app_ils.git

  3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:

    $ mkvirtualenv invenio_app_ils
$ cd invenio_app_ils/
$ pip install -e .[all]

  4. Create a branch for local development:

    $ git checkout -b name-of-your-bugfix-or-feature

    Now you can make your changes locally.

  5. When you’re done making changes, check that your changes pass tests:

    $ ./run-tests.sh

    The tests will provide you with test coverage and also check PEP8 (code style), PEP257 (documentation), flake8 as well as build the Sphinx documentation and run doctests.

  6. Commit your changes and push your branch to GitHub:

    $ git add .
$ git commit -s
    -m "component: title without verbs"
    -m "* NEW Adds your new feature."
    -m "* FIX Fixes an existing issue."
    -m "* BETTER Improves and existing feature."
    -m "* Changes something that should not be visible in release notes."
$ git push origin name-of-your-bugfix-or-feature

  7. Submit a pull request through the GitHub website.

Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

  1. The pull request should include tests and must not decrease test coverage.
  2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring.
  3. The pull request should work for Python 2.7, 3.3, 3.4 and 3.5. Check https://travis-ci.org/invenio_app_ils/invenio_app_ils/pull_requests and make sure that the tests pass for all supported Python versions.

Changes

License

MIT License

Copyright (C) 2018 CERN.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Note

In applying this license, CERN does not waive the privileges and immunities granted to it by virtue of its status as an Intergovernmental Organization or submit itself to any jurisdiction.

Authors

  • CERN