diff options
Diffstat (limited to 'README.org')
| -rw-r--r-- | README.org | 127 |
1 files changed, 126 insertions, 1 deletions
@@ -1,5 +1,6 @@ #+STARTUP: inlineimages #+TITLE: GeneNetwork Quality Control Application +#+OPTIONS: ^:{} ** Project Goals @@ -40,6 +41,130 @@ This repository can be used as a guix channel. "F370 F409 854B 90E3 52F3 AB01 362B 0BB8 B81D 5A42")))) #+END_SRC +** Configuration + +This system requires that some configurations be in place to operate correctly. +The following sections detail the configuration variables. + +*** System Configurations + +**** *Config*: =LOG_LEVEL= +*Default*: WARNING + +We use logging to track the operation of the system, noting major events, and +conditions in the system as it runs. The =LOG_LEVEL= variable controls how much +of that information we want to track, and the severity of said information. + +**** *Config*: =SECRET_KEY= + +*Mandatory* + +This is a key used for signing cookies for more secure tamper-proof sessions. +Without it, Flask will generate a random key for each running thread/process of +the system, leading to some really difficult to debug consequences. + +/Avoid the aggravation! Just set a secret key and be done with it/. + +For some more information on Flask's =SECRET_KEY= have a look at the following +resources: + +- https://flask.palletsprojects.com/en/3.0.x/config/#SECRET_KEY +- https://flask.palletsprojects.com/en/3.0.x/quickstart/#sessions +- https://stackoverflow.com/a/48596852 + +**** *Config*: `UPLOAD_FOLDER` + +*Default*: /tmp/qc_app_files + +This is the directory where all uploaded files are stored. + +Files are to be stored here temporary, while they are still being processed. +Down the line, we will probably have a different location for files that have +passed QC and whose data has been accepted into the system. + +*Development Note*: Other files we store here that we will need to extract to a +separate configuration are: + +- Files with outputs from background processes triggered by this system +- /list others here…/ + +**** *Config*: =SQL_URI= +*Mandatory* + +This defines the connection URI to the database. + +This is a *MANDATORY* configuration variable: without it, the uploader will not +work as expected, if at all. + +Presently, we use the MariaDB database, and thus, the URI to the database will +take the form + +#+BEGIN_EXAMPLE +mysql://<username>:<password>@<hostname-or-ip>:<port>/<database-name> +#+END_EXAMPLE + +The parts of the URI of note are: + +- =<username>=: This is the username to use to connect to the MariaDB server +- =<password>=: A password to authenticate the user with the MariaDB server +- =<hostname-or-ip>=: The domain name or IP address of the computer hosting the + MariaDB server +- =<port>=: The port to connect to for the MariaDB server, on the computer + hosting MariaDB +- =<database-name>=: The database to connect to + +*** Redis Configurations + +**** *Config*: =REDIS_URL= + +*Default*: redis:// + +This is the connection URI to the Redis server. The default connection parameter +above tries to connect to a redis server on the same host that the uploader is +running on. + +*Note to Fred*: We should probably rename this =REDIS_URI= for consistency. + +The Redis connection URI has the general form: + +#+BEGIN_EXAMPLE +redis://<username>:<password>@<hostname-or-ip>:<port>/<dbnum> +#+END_EXAMPLE + +and the parts of the URI of note are: + +- =<username>=: This is the username to use to connect to the Redis server +- =<password>=: A password to authenticate the user with the Redis server +- =<hostname-or-ip>=: The domain name or IP address of the computer hosting the + Redis server +- =<port>=: The port to connect to for the Redis server, on the computer + hosting Redis +- =<dbnum>=: A number identifying the database to connect to + + Here is [a resource](https://github.com/lettuce-io/lettuce-core/wiki/Redis-URI-and-connection-details) + on other ways to construct Redis connection URIs. + +**** *Config*: =JOBS_TTL_SECONDS= + +*Default*: 1209600 seconds (14 days) + +This is the "Time-To-Live" for the keys in redis. Most of the keys we store in +Redis from this system do not need to be retained forever. The TTL determines +how long (in seconds) to keep the keys around for. + +**** *Config*: =GNQC_REDIS_PREFIX= + +*Default*: GNQC + +This system could find itself sharing a Redis server with other (related) +applications such as [GN2](https://github.com/genenetwork/genenetwork2) and +[GN3](https://github.com/genenetwork/genenetwork3). + +The =GNQC_REDIS_PREFIX= configuration is prepended to the keys being saved by +this system to redis. For example, if ~GNQC_REDIS_PREFIX=GNQC~ and you want to +set up a hash with the key =users=, the effective key in redis will be +~GNQC:users~. + ** Development For reproducibility, this project is developed using guix. @@ -136,7 +261,7 @@ guix package [-p /path/to/qc/profile] -f guix.scm :CUSTOM_ID: run-cli-version :END: -Install the application as shown in the [[Installing QC]] section above. +Install the application as shown in the /Installing QC/ section above. To run qc against a file, the syntax is: #+BEGIN_SRC shell |