Sci-ModoM

Production Setup

The recommended way to run the application in production is a container setup. See Container Setup for details.

Development Setup

Overview

The application consists of the following components:

Database: MariaDB
Server: A REST-API backend using Python3 and Flask
Client: A Web-GUI using Vue.js

All components can be run locally.

Database setup

Set up a MariaDB database. One way to do this is to run a MariaDB container image. See the Development Setup section in Container Setup on how to do this. A local MariaDB database is also possible with similar setup steps. The following steps are required:

Create a database
Create a database user
Grant access to the database to this user

Server setup

Create a Python3 virtual environment with your preferred method and activate it, e.g.:

python3 -m venv ~/.virtualenvs/scimodom
. ~/.virtualenvs/scimodom/bin/activate

Get the source code and install :

git clone https://github.com/dieterich-lab/scimodom.git
cd scimodom
pip install --upgrade pip setuptools
pip --verbose install 2>&1 | tee install.log

Note: The package depends on mysqlclient. You may have to install MySQL development headers and libraries before. You also need a working installation of Bedtools, e.g. pre-compiled binaries.

Set up your environment configuration in server/.env like this:

DATABASE_URI=mysql+mysqldb://scimodom:*some password*@127.0.0.1:3306/scimodom
SECRET_KEY=*some secret*
SESSION_COOKIE_SAMESITE=None
SESSION_COOKIE_SECURE=True
UPLOAD_PATH=/path/to/upload
DATA_PATH=/path/to/data
SMTP_SERVER=outgoing-email-server.my-site.org
SMTP_FROM_ADDRESS=sci-modom-admin@my-site.org
PUBLIC_URL=https://sci-modom.my-site.org

Important: If the host name localhost is used in the DATABASE_URI the database driver will assume that the database is contacted using a named socket. That will not work if a container is used!

Now the database schema can be initialized by executing this command under the server directory:

alembic upgrade head

The API backend can be started with:

# under client/server
flask run

Most Python IDEs can run this process in the integrated debugger.

Development

For development:

pip --verbose install -e '.[dev,tests,docs]' 2>&1 | tee install.log

Pre-commit and static type checker

Under the server directory:

# first time, you might have to
pre-commit install
# the first time pre-commit runs on a file it will automatically download, install, and run the hook
# runs on all file at commit or run manually
pre-commit run --all-files
# to run individual hooks use pre-commit run <hook_id>

# run static type checker
mypy -p scimodom

Tests

To execute the Python tests run under the server directory:

pytest tests

Client setup

To bring up the frontend, go to the client directory and execute:

npm install
npm run dev

Now the application is available here:

http://localhost:5173/

To test the bundled frontend, run under the client directory:

npm run build

This will populate the folder client/dist with the bundled static HTML/JavaScript code as it should be deployed in production. The server can now also serve this code. The complete application is now also available under the Flask development server URL:

http://127.0.0.1:5000

Development Hints

Database schema updates

The database schema is tracked using Alembic. Changes to the database must be coded at two locations:

An Alembic version must be defined in server/migrations/versions
The model must be updated in server/src/scimodom/database/models.py

Any change to the schema is generally tracked with:

# under client/server
alembic revision --autogenerate [-m "message"]
alembic upgrade head

License

GNU Affero General Public Licence (AGPL) version 3.

dieterich-lab / scimodom

readme