Installation

You can install and use the openNPL package in any system that supports python or docker

Installation via Docker

Installation via docker is recommended as it provides a streamlined and fast setup of an openNPL instance. If you do not want to use docker scroll further down for Manual installation from sources

Install Docker

Note

A working docker installation is required! Docker is available for many operating systems and platforms (Windows, MacOS, Linux, running on Intel/AMD or ARM chipsets among others). Follow the installation instructions here.

Once the installation is complete, make sure the docker service is running by testing that you can run the docker ‘hello-world’ application.

sudo service docker start
sudo docker run hello-world

Now we are ready for the next step. You can either pull an image from Docker Hub or build a local image:

Pull the openNPL image from Docker Hub

You can pull and run the latest image from Docker Hub (This method is recommended if you do not want to mess at all with the source distribution).

Note

We are also providing images also for the ARM/v7 architecture (Raspberry Pi). Check the root of our docker hub for what is currently available

Start by issuing a docker pull command:

docker pull openrisk/opennpl_web:latest
docker run -p 8001:8080 openrisk/opennpl_web:latest

If all went well you have now a running instance of openNPL in your local machine. Access it by pointing your browser to http://localhost:8001 and login with admin/admin credentials.

The API endpoints are accessible at http://localhost:8001/api

Note

If you want to work with a different image check what is available at our docker hub list

Building a local docker image

Alternatively you can build your own local docker image. After you fetch the distribution from the github repository (as per manual installation instructions below), in the root directory of the distribution issue:

cd openNPL
docker build -t opennpl_web:latest .
docker run -p 8001:8080 opennpl_web:latest

Again, access the running instance of openNPL by pointing your browser to http://localhost:8001 and login with the default admin/admin credentials

Manual installation from sources

The manual installation path is recommended if you want to dig into and inspect the openNPL code base or if you want to contribute to openNPL.

Dependencies / Requirements

Note

A Linux based system is recommended but with minor tweaks it is in principle also possible to deploy in Windows systems

  • openNPL requires a working Python 3 installation (including pip)

  • Python >= 3.10

  • Django >= 4.0

  • The precise python library dependencies are listed in the Requirements.txt file.

  • openNPL may work with earlier versions of these packages but this has not been tested

  • A linux based system is recommended. Some tweaks are required for Windows but is in principle also possible to deploy there

Note

The current User Interface (UI) of openNPL is desktop oriented and might not work properly in smaller (mobile) screens

Manual installation procedure

Step 1. Download the github sources to your preferred directory:

git clone https://github.com/open-risk/openNPL

Step 2. Create a virtualenv. It is advisable to install the platform in a virtualenv so as not to interfere with your system’s python distribution

virtualenv -p python3 venv
source venv/bin/activate

Step 3. Install the required dependencies (The core dependency is Django and its own dependencies, in addition the Grappelli skin as the admin interface)

pip3 install -r requirements.txt

Step 4. Make the required django migrations. The project is setup to use sqlite3. This step will ensure the database has the right tables.

cd openNPL
python manage.py makemigrations
python manage.py migrate

Step 5. Create a superuser. Suggestion: Use admin/admin as login/password as a reminder that this instance of openNPL should NOT be used for anything remotely sensitive!

python3 manage.py createsuperuser

Step 6. Collect static files (to ensure the interface will render properly)

python3 manage.py collectstatic --no-input

Step 7. Insert some dummy data (optional). Without this the database will be empty.

bash loadfixtures.sh

Step 8. Run the server. The default port is 8000 but if (by any chance) this port is already used in your computer there will be another assigned. Be sure to note the assigned port and use it instead.

python3 manage.py runserver

Step 9. Login with your browser. Finally in your favorite browser (e.g. Firefox from Mozilla), enter the url http://localhost:8001 and login with admin/admin credentials.

Note

8000 is the default port, if that is already in use, you can select an alternative one as follows:

python3 manage.py runserver localhost:8081

Troubleshooting

The above steps are typical Django project installation steps. If you experience trouble at any point, the Django online FAQ should help you out.

Note

The project uses an sqlite3 database for good reason! If things go pear-shaped with your database simply remove the file and start again.

We welcome your feedback and support. Please raise a github ticket if you want to report a bug or need a new feature. For contributions check our Contribution and Code of Conduct docs.