biblib-service

Astrophysic Data System's library service

development

NOTE: This method is now deprecated and only works on x64 machines.

A Vagrantfile and puppet manifest are available for development within a virtual machine. To use the vagrant VM defined here you will need to install Vagrant and VirtualBox.

• Vagrant
• VirtualBox

To load and enter the VM: vagrant up && vagrant ssh

tests

Run the tests using pytest:

docker run -d --name postgres -e POSTGRES_USER="postgres" -e POSTGRES_PASSWORD="postgres" -p 5432:5432 postgres:12.6

# Setup environment
python3 -m venv python
source python/bin/activate

# Install with legacy build support (requires pip 24 and specific setuptools)
python -m pip install "pip==24" setuptools==57.5.0 wheel
pip install -e ".[dev]"

# Run tests
pytest

Layout

Tests are split into three (excessive) stages:

1. Functional tests (biblib/tests/functional_tests/): this tests a workflow, for example, a user adding a library and then trying to delete it - and testing everything behaves as expected via the REST work flow
2. Unit tests, level 1 (biblib/tests/unit_tests/test_webservices.py): this tests the above workflow on the REST end points
3. Unit tests, level 2 (biblib/tests/unit_tests/test_views.py): this tests the logic of functions that are used within views (end points), and is usually the most fine grained testing
4. Other unit testing: other tests that are testing other parts, such as manage scripts are in their own unit tests, e.g., biblib/tests/unit_tests/test_manage.py.

All tests have been written top down, or in a Test-Driven Development approach, so keep this in mind when reading the tests. All the logic has been built based on these tests, so if you were to add something, I'd advise you first create a test for your expected behaviour, and build the logic until it works.

Running Biblib Locally

To run a version of Biblib locally, a postgres database needs to be created and properly formatted for use with Biblib. This can be done with a local postgres instance or in a docker container using the following commands. local_config.py should be created in biblib/ and the environment variables must be adjusted to reflect the local environment.

# Setup database
docker run -d -e POSTGRES_USER="postgres" -e POSTGRES_PASSWORD="postgres" -p 5432:5432 --name postgres postgres:12.6
docker exec -it postgres psql -U postgres -c "CREATE ROLE biblib_service WITH LOGIN PASSWORD 'biblib_service';"
docker exec -it postgres psql -U postgres -c "CREATE DATABASE biblib_service;"
docker exec -it postgres psql -U postgres -c "GRANT ALL PRIVILEGES ON DATABASE biblib_service TO biblib_service;"

Run migrations

In order for alembic to have access to the models metadata, the biblib-service directory must be added to the PYTHONPATH

export PYTHONPATH=$(pwd):$PYTHONPATH python biblib/manage.py syncdb # This will sync users and can be used to initialize schema via alembic indirectly or directly: alembic upgrade head

A test version of the microservice can then be deployed using:
```bash
export FLASK_APP=biblib/app.py
flask run --port 4000

or via the legacy entrypoint:

python wsgi.py

Database versioning

Database versioning is managed using Alembic. You can upgrade to the latest revision or downgrade to a previous one using the following commands:

# Upgrade to latest revision
alembic upgrade head

# Downgrade revision
alembic downgrade <revision>

# Create a new revision
alembic revision --autogenerate -m "revision description"

New revisions of libraries and notes are created automatically by sqlalchemy-continuum whenever a record is updated and committed to the database.

deployment

The only thing to take care of when making a deployment is the migration of the backend database. Libraries uses specific features of PostgreSQL, such as UUID and JSON-store, so you should think carefully if you wish to change the backend. The use of flask-migrate for database migrations has been replaced by directly calling alembic.

Feature additions

Please see the issues page for lists of features that have been kept in mind during the building of private libraries.