Quick start

There are two ways to get started quickly with Protari: using the predefined Docker images or installing Protari yourself.

Architectural overview

API diagram

Building and running Protari using Docker

The recommended way to get started with a sample version of the Protari is to build the provided Docker images for the API and the Table UI and then use one of the provided docker-compose scripts to get a sample implementation up and running.

Note: by default, the Protari API Docker image uses an SQLite database which does not provide the functionality required to perturb means and sums in Protari (at least using the TBE algorithm).

1. Build the API image

To build the protari/api Docker image, checkout the code from the protari-sample repository, navigate to the base folder of the checked out repository and run

docker build -t protari/api:local --build-arg ssh_prv_key="$(cat docker_config/docker_protari_api)" --build-arg ssh_pub_key="$(cat docker_config/docker_protari_api.pub)" --squash .

2. Build the Table-UI image

To build the protari/table-ui Docker image, checkout the code from the table-ui-sample repository, navigate to the table_ui_docker_image directory within the checked out repository and run

docker build -t protari/table-ui:local --build-arg ssh_prv_key="$(cat docker_protari_api)" --build-arg ssh_pub_key="$(cat docker_protari_api.pub)" --squash .

Note: the protari/table-ui Docker image is configured to run in demonstration mode by default. This means it has no authentication, and is configured to talk to the protari/api Docker image in the manner of the example docker-compose scripts discussed below.

3. Combine Protari API and Protari Table UI using docker-compose

Assuming you have already built protari/api:local and protari/web:local, you can simply navigate to the docker_compose/basic folder within the table-ui-sample repository and run:

docker-compose up

Once the stack has started up, the UI will be available at http://localhost:8443 and the API will be available at http://localhost:8080.

Note: a more complex docker-compose example, detailing how to run Protari with different configuration, can be found in the docker_compose/binding folder. See the README in the table-ui-sample repository for details.

Installing Protari yourself

Another way to run the Protari API is to import it as a package into your own python module (the "Protari instance" in the above diagram).

The protari-sample repository is a ready-to-go example. It contains some sample datasets and some sample data.

git clone protari-sample and follow the instructions provided there. The gist of those instructions is provided below.

If you want to develop the Protari libraries themselves, see the Developer's guide to setting up Protari.

The code relies on git+ssh to refer to other dependencies, so you will need to register your ssh key.

1. Choose the latest tagged version of protari-sample

Type git tag and choose the latest tag shown (eg. 1.0.0). Then type:

git checkout 1.0.0  # Replace the version with the latest tag.

2. Install Python, pip and pipenv

See the pipenv documentation for the steps to install python, pip and pipenv. This link may be helpful for linux users.

The API has been developed for Python 3.6, although later versions may work too.

3. Install the Required Packages

Enter the protari-sample directory, install the required packages into a virtual environment (including the ability to connect to a Postgres database), and enter that environment, via:

pipenv install --dev
pipenv shell

Note pipenv install --dev installs the protari-setup library, which is not required to run the API, but is required to build the database. (In production, where you are connecting to a pre-existing database, you would use pipenv install without the --dev.)

4. Set up a Sample Database

Ensure your database server is running, eg. installing a postgres server.

Then, still in the protari-sample directory, type:

./bin/build_db

5. Run the API's dev server

You can now run the API by typing (again, still in the protari-sample directory):

python application.py

You can test it out in your browser by navigating to http://localhost:8080/v1/ui/. (The v1 may change. See the file protari-api/swagger.yaml file for the current version.)

That page provides an interface for exploring the API. Alternatively you can check out the full API specification at http://localhost:8080/v1/swagger.json.

Note – do not use this development web server in production, as it does not scale well and serves only one request at a time. Some of the options available for properly running Flask in production are documented in the Flask documentation here. The server can be anything that supports WSGI (eg. Apache with mod_wsgi or nginx). The only required static files are those that provide the swagger UI for the API, if enabled.