You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+63-79Lines changed: 63 additions & 79 deletions
Original file line number
Diff line number
Diff line change
@@ -1,154 +1,145 @@
1
1
# Sci-ModoM
2
2
3
-
## Overview
4
-
5
3
The application consists of the following components:
6
4
7
5
- Database: MariaDB
8
-
- Server: A REST-API backend using Python3 and Flask
6
+
- Server: A REST-API backend using the SQLAlchemy Database Toolkit for Python and Flask
9
7
- Client: A Web-GUI using Vue.js
10
8
11
-
### General setup
9
+
## General setup
10
+
11
+
At launch time, the app uses tables defined in `SetupService` to populate the database. These tables **must** exist and be located under `IMPORT_PATH`. By default, this path is located under _server/import_, and can be specified in the environment file. Once setup is complete, assembly and annotation files must be added. See [Flask CLI - Setup](https://dieterich-lab.github.io/scimodom/flask.html#setup) for details.
12
12
13
-
At lauchtime, the app uses tables defined in `SetupService` to populate the database. These tables **must**exist. They are used both in development and production. They **must** be located under `IMPORT_PATH` (defaults to _server/import_, or specify in _.env_ file).
13
+
For project and data management, consult the **Documentation**tab on the Web-GUI, or [Flask CLI - Project and data management](https://dieterich-lab.github.io/scimodom/flask.html#project-and-data-management).
14
14
15
15
## Production setup
16
16
17
-
The recommended way to run Sci-ModoM in production is to use podman compose to create, manage, and deploy the application and the database containers, see [Container Setup](docker/CONTAINER_SETUP.md) for details.
17
+
The recommended way to run Sci-ModoM in production is to use Podman to create, manage, and deploy the application and the database containers, see [Container setup](docker/CONTAINER_SETUP.md) for details.
18
18
19
19
## Development setup
20
20
21
21
### Database setup
22
22
23
-
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](docker/CONTAINER_SETUP.md). The following steps are required:
24
-
25
-
- Create a database
26
-
- Create a database user
27
-
- Grant access to the database to this user
23
+
Set up a MariaDB database. One way to do this is to run a MariaDB container image, see the _General_ and _Development setup_ sections in [Container setup](docker/CONTAINER_SETUP.md).
28
24
29
25
### Server setup
30
26
31
-
Create a Python3 virtual environment with your preferred method and activate it_e.g._:
27
+
Create a Python3 virtual environment and activate it:
**Note:** The package depends on [mysqlclient](https://pypi.org/project/mysqlclient/). You may have to install MySQL development headers and libraries before. You also need a working installation of [Bedtools](https://bedtools.readthedocs.io/en/latest/), _e.g._[pre-compiled binaries](https://bedtools.readthedocs.io/en/latest/content/installation.html#downloading-a-pre-compiled-binary).
50
44
51
-
Set up your environment configuration in _server/.env_ like this:
45
+
Set up your environment configuration in _server/.env_:
where `PASSWORD` is the password for the scimodom user for the MariaDB database in _docker/secrets/mariadb-scimodom_, `3307` is the `MARIADB_DEV_PORT` (we recommend to use a non-standard port _e.g._ 3307 to avoid clashes with a local MariaDB/MySQL installation), and `SECRET_KEY` is the key found in _docker/secrets/flask-secret_, see [Container setup](docker/CONTAINER_SETUP.md) for details. You need to adjust the paths, and make sure they are valid and exist.
62
+
67
63
**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
68
64
socket. That will not work if a container is used!
69
65
70
-
In addition to _server/.env/_, a Flask-specific configuration in _server/.flaskenv_can be used:
66
+
You can also create a _server/.flaskenv_file with Flask-only variables:
71
67
72
-
```
68
+
```bash
73
69
FLASK_APP=src/scimodom/app
74
70
FLASK_DEBUG=True
75
71
```
76
72
77
-
Now the database container must be started under the _docker_ directory:
73
+
#### Running the application
78
74
79
-
```bash
80
-
# under scimodom/docker
81
-
docker compose -f docker-compose-db-only.yml up -d
82
-
```
83
-
84
-
The database schema can then be initialized by executing this command under the _server_ directory:
75
+
Start the database container under the _docker_ directory, see [Container setup](docker/CONTAINER_SETUP.md) (Development setup).
76
+
Under the _server_ directory, initialize the database schema:
85
77
86
78
```bash
87
-
# under scimodom/server
88
79
alembic upgrade head
89
80
```
90
81
91
-
The API backend can be started with:
82
+
and start the API backend:
92
83
93
84
```bash
94
-
# under scimodom/server
95
85
flask run
96
86
```
97
87
98
-
Most Python IDEs can run this process in the integrated debugger.
88
+
Most Python IDEs can run this process in the integrated debugger. You are now ready to add assemblies, annotations, projects, and data (General setup).
99
89
100
-
###Client setup
90
+
##### Email functionality, local login and registration
101
91
102
-
To bring up the frontend, go to the _client_ directory and execute:
92
+
To register in development mode, use the _Sign up_ button. This requires a functional email server. You first need build the frontend (see Client setup below). Once you receive a link via email, click on this link, but change the frontend server address to that of the Flask development server URL, _e.g._ change http://localhost:5173/ to http://localhost:5000. This is only necessary if you run the database using a container and connect it with the local Flask application.
103
93
104
-
```bash
105
-
# under scimodom/client
106
-
npm install # first time install
107
-
npm run dev
108
-
```
109
-
110
-
Now the application is available here:
94
+
Note that email functionality may be limited, as your mail server must be willing to relay emails for your `SMTP_FROM_ADDRESS`, _e.g._ Google or Gmail addresses will most likely not work. This may be problematic if you wish to register, as registration is done via a link sent by email. One way to avoid this problem is to patch the database. Open a python console under your environment and do the following
111
95
112
-
-http://localhost:5173/
96
+
```python
97
+
from werkzeug.security import generate_password_hash
# this will return e.g. 'pbkdf2:sha256:600000$vpYjirPAT8xBuPHo$1001474730f96085cdafbf0f159d12e20ec36342b4faddbf226d637c695ee642'
100
+
```
113
101
114
-
To test the bundled frontend, run under the _client_ directory:
102
+
Then go to the database, see _e.g._[Container setup - Manual database connection](docker/CONTAINER_SETUP.md) and do the following:
115
103
116
-
```bash
117
-
npm run build
104
+
```mysql
105
+
INSERT INTO user (email, state, password_hash) VALUES ('test@uni-heidelberg', 'active', 'pbkdf2:sha256:600000$vpYjirPAT8xBuPHo$1001474730f96085cdafbf0f159d12e20ec36342b4faddbf226d637c695ee642');
118
106
```
119
107
120
-
This will populate the folder _client/dist_ with the bundled static HTML/JavaScript code as it should be deployed in production.
121
-
The server can now also serve this code. The complete application is now also available under the Flask development server URL:
122
-
123
-
-http://127.0.0.1:5000
108
+
A new user is now registered, and you can login using whatever email address you used _e.g._ "test@uni-heidelberg" with the chosen password _e.g._ "mypassword".
124
109
125
-
#### Local login
110
+
###Client setup
126
111
127
-
Registration is completed via email. These environment variables are required:
112
+
The first time, you need to install the local packages that the project needs, go to the _client_ directory and execute:
**Important:** Make sure to build the frontend beforehand (see above). After receiving the registration link via email, click on the link, but change the default port `5173`to `5000` to point to the Flask development server URL.
118
+
This creates a _node_modules_ folder. You are now ready to bring up the frontend
135
119
136
-
Alternatively, you can patch the database (add user).
120
+
```bash
121
+
npm run dev
122
+
```
137
123
138
-
### Development hints
124
+
The application is now available at http://localhost:5173/, and any change you make _e.g._ to the HTML code will be reflected in the page you see in your browser.
139
125
140
-
For development:
126
+
To test the bundled frontend, run:
141
127
142
128
```bash
143
-
pip --verbose install -e '.[dev,tests,docs]'2>&1| tee install.log
129
+
npm run build
144
130
```
145
131
132
+
This will populate the folder _dist_ with the bundled static HTML/JavaScript code as it should be deployed in production.
133
+
The server can now also serve this code. The complete application is now also available under the Flask development server URL _e.g._ at http://127.0.0.1:5000.
134
+
135
+
### Development hints
136
+
146
137
#### Pre-commit and static type checker
147
138
148
139
Under the _server_ directory:
149
140
150
141
```bash
151
-
# first time, you might have to
142
+
#the first time, you might have to
152
143
pre-commit install
153
144
# the first time pre-commit runs on a file it will automatically download, install, and run the hook
154
145
# runs on all file at commit or run manually
@@ -161,30 +152,23 @@ mypy -p scimodom
161
152
162
153
#### Tests
163
154
164
-
To execute the Python tests run under the _server_ directory:
155
+
To execute the tests, run under the _server_ directory:
165
156
166
157
```bash
167
158
pytest tests
168
159
```
169
160
170
-
To run pytest from command line, adjust the `PYTHONPATH`_e.g._
0 commit comments