Musical Instruments Corrosion Data documentation

This is the documentation for the website for Musical Instruments Corrosion Data.

The code consists of the main.py script which serves all the websites routes and utilizes the various libraries, both included and sourced elsewhere.

The main requirements are:

Python 3.12 or newer
Python virtual environment with the corrosion data code
pip (to install packages in the venv)
Bottle 0.13.2 (or possibly newer) - to serve the site
openpyxl 3.1.5 (or possibly newer) - for reading/writing excel-files
plotly 5.24.1 (or possibly newer) - for creating graphs
sphinx - for auto-rendering the documentation
sphinx_rtd_theme - theme for sphinx

In the virtual environment, you can start the bottle-server with:

python3 main.py

Installation

To install the corrosion website, you have to do these main steps:

Create the python virtual environment (venv)
Copy the source files to the venv
Install the required packages in the venv using pip

Please see below for detailed instructions on how to do these steps.

Create The Virtual Environment

This is a short guide to creating the python virtual environment (venv), which in this case has already been done, so it does not need to be done. But in just in case, here’s how.

Go to the folder where you intend to create the venv under. We recommend that you create a top folder, where the venv will become its sub-folder.
While standing in that created folder, write:

python3 -m venv corrosion

Hit enter and the corrosion-venv will be created in the “corrosion”-folder.

In order to use the environment you have to use the shell source command in conjunction with the activate script that resides in the venv you just created:

source corrosion/bin/activate

Then you can proceed to install packages and other things needed in the venv.

Install Packages

This is how to install packages in the venv that you created.

First activate the venv for use:

source corrosion/bin/activate
cd corrosion

Then proceed to install packages:

pip install bottle
pip install openpyxl
pip install plotly
pip install sphinx sphinx_rtd_theme

Then head to a web-browser at localhost:8080

How To Setup Sphinx For Documentation Rendering

After having installed the necessary packages, including sphinx, you can proceed to setup the documentation rendering. This has already been done, so this is here primarily for instructional purposes.

First, create the docs folder:

mkdir docs
cd docs

Then create the sphinx folder:

sphinx-quickstart

Answer just the defaults on all questions from the script.

In the docs-folder should now resides several files. Edit the conf.py file and add the following to its top:

import os
import sys
sys.path.insert(0, os.path.abspath('..'))

Set the extensions-parameter of the conf.py file to the following:

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.viewcode',
    'sphinx.ext.napoleon'
]

Change the html_theme parameter to:

html_theme = 'sphinx_rtd_theme'

Save the conf.py file and exit it.

Then go to the corrosion folder and write:

sphinx-apidoc -o docs *

And it will generate .rst files for your code in the docs-folder. This must be repeated for any new modules that are added.

In order to render the html of the documentation at any point, run:

make html

Then the new html code should be available in the docs-folder under “_build/html/index.html”.

How To Install On Apache Web-Server

There are several ways of getting this script to work on an Apache web-server. The method that has been tested is by using mod_wsgi and the WSGI-framework.

This requires the following of Apache:

Installed with mod_wsgi and it has been enabled.
Setup with a VirtualHost-configuration.

You also need to install the code-base of the Corrosion Data site in a location which will be the document-root of it.

In the next example of configurations settings, I will be using the document root as:

/var/www/html

Another document folder can be chosen as long as the illustrated hierarchy is intact.

The mentioned VirtualHost-configuration need to have the following settings added to it:

DocumentRoot "/var/www/html"

WSGIDaemonProcess www-data python-home=/var/www/html/corrosion
WSGIPassAuthorization On

WSGIProcessGroup www-data
WSGIApplicationGroup %{GLOBAL}

WSGIScriptAlias / /var/www/html/corrosion/main.py

<Directory /var/www/html/corrosion/>
    Require all granted
</Directory>

In addition we recommend setting the CORROSION_PATH environment variable through the apache envvars-file (typically located in /etc/apache2/envvars) by adding the following to the end of the file:

export CORROSION_PATH=/var/www/html

This is the best place to add it, since normal environment variables or SetEnv statements are either not part of the apache2-server load environment or executed too late to be available through the WSGI framework. One can use the apache SetEnv statement and have variables available later on (in the WSGI page request itself), but the CORROSION_PATH needs to work earlier upon the script loading and before any web-client requests have been sent. Remember that after setting it the first time, the apache-server needs to be restarted/reloaded.

The codebase should be unpacked while standing in the /var/www/html folder, so that the structure is created from there.

Please also note that there will be created a folder called “db” located in:

/var/www/html/corrosion/db

that contains the database of the corrosion data site. It is important that the Apache web-server has read- and write access to both the folder and the database file in the folder.

We recommend setting the following (while standing in the /var/www/html-folder):

chown www-data:root db
chmod 0771 db
chown www-data:www-data db/corrosion.db
chmod 0660 db/corrosion.db

The other parts of the codebase should work as it is when unpacked from a archive or retrieved from code repo.