diff --git a/.gitignore b/.gitignore index a5c14e44..4a196215 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,9 @@ # program/data folders .env +apache2/certs/* +!apache2/certs/.gitkeep +apache2/sites-enabled/* +!apache2/sites-enabled/sample bin config jbrowse/* diff --git a/Dockerfile b/Dockerfile index a1928cb2..2945d902 100644 --- a/Dockerfile +++ b/Dockerfile @@ -48,7 +48,7 @@ RUN curl -LO https://github.com/GMOD/jbrowse/releases/download/1.12.5-release/JB mv JBrowse-1.12.5 /var/www/html/jbrowse && \ rm JBrowse-1.12.5.zip && \ cd /var/www/html/jbrowse && ./setup.sh && \ - # Default FORCAST configuration for JBrowse. jbrowse/data/datasets.conf is mounted as a volume inside docker-compose.yaml for editing. + # Default FORCAST configuration for JBrowse. jbrowse/data/datasets.conf is mounted as a volume inside docker-compose.yaml, docker-compose-dev.yaml, and docker-compose-prod.yaml for editing. bash -c "echo -e 'classicMenu = true\ninclude += data/datasets.conf\n\n[aboutThisBrowser]\ntitle = FORCAST' >> /var/www/html/jbrowse/jbrowse.conf" && \ # Add favicon sed -i '6i\ ' /var/www/html/jbrowse/index.html @@ -63,6 +63,7 @@ WORKDIR /var/www/html RUN sed -i 's/^Timeout [[:digit:]]\+/Timeout 1200/g' /etc/apache2/apache2.conf # Replace the /usr/sbin/apachectl script that is called with the Apache master process that respects signals ENV APACHE_HTTPD exec /usr/sbin/apache2 +RUN a2enmod ssl CMD chmod 777 ./src/guide-finder/logs ./src/primer-design/files/* && \ mongod --fork --logpath /var/log/mongodb/mongod.log --dbpath /var/lib/mongodb && \ exec apache2-foreground \ No newline at end of file diff --git a/README.md b/README.md index 89bc7b01..2ca6f124 100644 --- a/README.md +++ b/README.md @@ -37,9 +37,13 @@ git clone https://github.com/ccmbioinfo/FORCAST.git Navigate to the cloned repository folder, copy the sample `config-sample` directory and `datasets.sample.conf` file, build the Docker image, and start the service container. ```bash -cp -r config-sample config && cp jbrowse/data/datasets.sample.conf jbrowse/data/datasets.conf +cp apache2/sites-enabled/sample/* apache2/sites-enabled && cp -r config-sample config && cp jbrowse/data/datasets.sample.conf jbrowse/data/datasets.conf ``` +#### SSL certificate (for production and staging environment) + +Copy the relevant SSL certificate files into the `apache2/certs` directory and modify the `forcast-ssl.conf` file accordingly (e.g., modify the `SSLCertificateFile`, `SSLCertificateKeyFile`, and `SSLCertificateChainFile` directives where applicable). Note that the `apache2/certs` directory is mounted as a volume at `/etc/apache2/certs` inside `docker-compose-dev.yaml` and `docker-compose-prod.yaml`. + ### For production environment (using `stable` tagged Docker image) To start and run the FORCAST Docker container: @@ -84,7 +88,7 @@ docker compose down --- -FORCAST should now be available on `localhost:80`, or port 80 of the hosting machine. +FORCAST should now be available on `localhost:80` or port 80 (and `localhost:443` or port 443 if you are running FORCAST in a staging or production) of the hosting machine. Genomes are downloaded from Ensembl. For a full list from the current release, see [Ensembl](https://ftp.ensembl.org/pub/current_fasta/). Not all of these have been tested with FORCAST. Please keep in mind the Ensembl release version @@ -111,9 +115,11 @@ _Drosophila melanogaster_ is known to not install properly due to using a differ ## Customization ### Custom Primer Design Settings + First, go to to [the primer3 website](http://bioinfo.ut.ee/primer3/) and enter the custom settings that you would like to use for the first attempt of primer design and click 'Download Settings' to save the file. Additionally, you may also specify and download 'retry attempt' settings to be used if no primers are found with the default settings. There is no limit to the number of retry attempts you can define. -Once all the settings files have been generated, ssh into the server hosting FORCAST and navigate to where the application is rooted (e.g. ```/var/www/html/FORCAST```). Within the ```config``` directory there should be a ```primer3settings.conf``` file and a directory, ```primer3settings```, where the default primer3 settings are stored. Replace these with your custom settings and edit the ```primer3settings.conf``` file to point to the new files like so: +Once all the settings files have been generated, ssh into the server hosting FORCAST and navigate to where the application is rooted (e.g. `/var/www/html/FORCAST`). Within the `config` directory there should be a `primer3settings.conf` file and a directory, `primer3settings`, where the default primer3 settings are stored. Replace these with your custom settings and edit the `primer3settings.conf` file to point to the new files like so: + ``` ATTEMPT_0_FILE=primer3settings/filename.txt ATTEMPT_1_FILE=primer3settings/filename1.txt @@ -121,19 +127,20 @@ ATTEMPT_1_DESC="Description of changes in ATTEMPT_1 file" ATTEMPT_2_FILE=primer3settings/filename2.txt ATTEMPT_2_DESC="Description of changes in ATTEMPT_2 file" ``` + The descriptions are optional but will be displayed to users if a design failure occurs. ### Custom RNA-guided Endonuclease (RGEN) Settings The `src/setup/rgens.json` defines the default RGEN settings: -| Shortform | PAM | PamLocation | MinGuideLength | MaxGuideLength | DefaultGuideLength | SeedRegion | Cleaves | OffTargetPAMs | Scores | -| --------- | --- | ----------- | -------------- | -------------- | ------------------ | ---------- | ------- | ------------- | ------ | -| SpCas9 (NGG) | NGG | downstream | 17 | 20 | 20 | -12 | -3 | NGG, NAG | MIT, CFD | -| AsCpf1/Cas12a | TTTV | upstream | 20 | 23 | - | +6 | +19,+23 | TTTV, TTTT, CTTA, TTCA | - | -| ScCas9 (NNG) | NNG | downstream | 20 | 20 | - | -12 | -3 | NNG | - | -| ScCas9 (NNGT) | NNGT | downstream | 20 | 20 | - | -12 | -3 | NNGT | - | -| SaCas9 | NNGRRT | downstream | 21 | 23 | - | -8 | -3 | NNGRRT, NNGRR | - | +| Shortform | PAM | PamLocation | MinGuideLength | MaxGuideLength | DefaultGuideLength | SeedRegion | Cleaves | OffTargetPAMs | Scores | +| ------------- | ------ | ----------- | -------------- | -------------- | ------------------ | ---------- | ------- | ---------------------- | -------- | +| SpCas9 (NGG) | NGG | downstream | 17 | 20 | 20 | -12 | -3 | NGG, NAG | MIT, CFD | +| AsCpf1/Cas12a | TTTV | upstream | 20 | 23 | - | +6 | +19,+23 | TTTV, TTTT, CTTA, TTCA | - | +| ScCas9 (NNG) | NNG | downstream | 20 | 20 | - | -12 | -3 | NNG | - | +| ScCas9 (NNGT) | NNGT | downstream | 20 | 20 | - | -12 | -3 | NNGT | - | +| SaCas9 | NNGRRT | downstream | 21 | 23 | - | -8 | -3 | NNGRRT, NNGRR | - | However, we recognize that these settings and defaults may not be applicable to all users. New RGENs can be added by specifying the RGEN parameters in the template below and appending to the `rgens.json` file. @@ -144,29 +151,38 @@ However, we recognize that these settings and defaults may not be applicable to Existing RGENs can have their settings and defaults modified in the file as well. In order to keep existing guides associated to their RGENs, it's recommended that the rgenIDs remain unchanged for existing entries. After modifying the `rgens.json` file, you can run the `load_RGENs.py` script in the same directory (`python3 load_RGENS.py`) and provide the desired command-line argument: + - `update`: modifies existing records based on the rgenID and adds new RGENs to the database (recommended) - `replace`: wipes and replaces RGEN database with new entries, potentially unlinking existing gRNA records from their RGEN. ## Migration + If using a previous version of FORCAST, existing Primers and Guides can be migrated to the new version by performing the following steps: -1) Navigate to the _existing_ FORCAST installation and make copies of the collections to migrate. Replace mm10 with your genome version, if it is different, and define a directory where the database files should be output. +1. Navigate to the _existing_ FORCAST installation and make copies of the collections to migrate. Replace mm10 with your genome version, if it is different, and define a directory where the database files should be output. + ``` mongodump --db=mm10 --collection=gRNAResultCollection -o mongodump --db=mm10 --collection=primerCollection -o ``` + This will place the .bson and .json files into a folder in your specified output directory. Transfer this folder to the new FORCAST installation if it is on a different machine. -2) On the server hosting the new FORCAST, run: +2. On the server hosting the new FORCAST, run: + ``` mongorestore --db=mm10 --collection gRNAResultCollection /gRNAResultCollection.bson mongorestore --db=mm10 --collection primerCollection /primerCollection.bson ``` -3) After restoring the database, the database documents need to be converted to the new format via a Python script: + +3. After restoring the database, the database documents need to be converted to the new format via a Python script: + ``` python3 src/helpers/MongoConverter.py ``` -4) Finally, the GFF files need to be re-written for the JBrowse tracks by a python script: + +4. Finally, the GFF files need to be re-written for the JBrowse tracks by a python script: + ``` python src/helpers/MongoHandler.py mm10 ``` @@ -182,6 +198,7 @@ FORCAST: a fully integrated and open source pipeline to design Cas-mediated muta Hillary Elrick, Viswateja Nelakuditi, Greg Clark, Michael Brudno, Arun K. Ramani, Lauryl M.J. Nutter bioRxiv 2020.04.21.053090; doi: https://doi.org/10.1101/2020.04.21.053090 ``` + ## Troubleshooting diff --git a/apache2/certs/.gitkeep b/apache2/certs/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/apache2/sites-enabled/sample/forcast-ssl.conf b/apache2/sites-enabled/sample/forcast-ssl.conf new file mode 100644 index 00000000..855152c4 --- /dev/null +++ b/apache2/sites-enabled/sample/forcast-ssl.conf @@ -0,0 +1,159 @@ + + #RedirectMatch permanent (.*) https://%{HTTP_HOST}%{REQUEST_URI} + RewriteEngine On + #RewriteCond %{HTTPS} off + RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI} [R=301,L] + + + + # The ServerName directive sets the request scheme, hostname and port that + # the server uses to identify itself. This is used when creating + # redirection URLs. In the context of virtual hosts, the ServerName + # specifies what hostname must appear in the request's Host: header to + # match this virtual host. For the default virtual host (this file) this + # value is not decisive as it is used as a last resort host regardless. + # However, you must set it for any further virtual host explicitly. + #ServerName www.example.com + + ServerAdmin webmaster@localhost + DocumentRoot /var/www/html + + # Available loglevels: trace8, ..., trace1, debug, info, notice, warn, + # error, crit, alert, emerg. + # It is also possible to configure the loglevel for particular + # modules, e.g. + #LogLevel info ssl:warn + + ErrorLog ${APACHE_LOG_DIR}/error.log + CustomLog ${APACHE_LOG_DIR}/access.log combined + + # For most configuration files from conf-available/, which are + # enabled or disabled at a global level, it is possible to + # include a line for only one particular virtual host. For example the + # following line enables the CGI configuration for this host only + # after it has been globally disabled with "a2disconf". + #Include conf-available/serve-cgi-bin.conf + + # SSL Engine Switch: + # Enable/Disable SSL for this virtual host. + SSLEngine on + + # A self-signed (snakeoil) certificate can be created by installing + # the ssl-cert package. See + # /usr/share/doc/apache2/README.Debian.gz for more info. + # If both key and certificate are stored in the same file, only the + # SSLCertificateFile directive is needed. + SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem + SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key + + # Server Certificate Chain: + # Point SSLCertificateChainFile at a file containing the + # concatenation of PEM encoded CA certificates which form the + # certificate chain for the server certificate. Alternatively + # the referenced file can be the same as SSLCertificateFile + # when the CA certificates are directly appended to the server + # certificate for convinience. + #SSLCertificateChainFile /etc/apache2/ssl.crt/server-ca.crt + + # Certificate Authority (CA): + # Set the CA certificate verification path where to find CA + # certificates for client authentication or alternatively one + # huge file containing all of them (file must be PEM encoded) + # Note: Inside SSLCACertificatePath you need hash symlinks + # to point to the certificate files. Use the provided + # Makefile to update the hash symlinks after changes. + #SSLCACertificatePath /etc/ssl/certs/ + #SSLCACertificateFile /etc/apache2/ssl.crt/ca-bundle.crt + + # Certificate Revocation Lists (CRL): + # Set the CA revocation path where to find CA CRLs for client + # authentication or alternatively one huge file containing all + # of them (file must be PEM encoded) + # Note: Inside SSLCARevocationPath you need hash symlinks + # to point to the certificate files. Use the provided + # Makefile to update the hash symlinks after changes. + #SSLCARevocationPath /etc/apache2/ssl.crl/ + #SSLCARevocationFile /etc/apache2/ssl.crl/ca-bundle.crl + + # Client Authentication (Type): + # Client certificate verification type and depth. Types are + # none, optional, require and optional_no_ca. Depth is a + # number which specifies how deeply to verify the certificate + # issuer chain before deciding the certificate is not valid. + #SSLVerifyClient require + #SSLVerifyDepth 10 + + # SSL Engine Options: + # Set various options for the SSL engine. + # o FakeBasicAuth: + # Translate the client X.509 into a Basic Authorisation. This means that + # the standard Auth/DBMAuth methods can be used for access control. The + # user name is the `one line' version of the client's X.509 certificate. + # Note that no password is obtained from the user. Every entry in the user + # file needs this password: `xxj31ZMTZzkVA'. + # o ExportCertData: + # This exports two additional environment variables: SSL_CLIENT_CERT and + # SSL_SERVER_CERT. These contain the PEM-encoded certificates of the + # server (always existing) and the client (only existing when client + # authentication is used). This can be used to import the certificates + # into CGI scripts. + # o StdEnvVars: + # This exports the standard SSL/TLS related `SSL_*' environment variables. + # Per default this exportation is switched off for performance reasons, + # because the extraction step is an expensive operation and is usually + # useless for serving static content. So one usually enables the + # exportation for CGI and SSI requests only. + # o OptRenegotiate: + # This enables optimized SSL connection renegotiation handling when SSL + # directives are used in per-directory context. + #SSLOptions +FakeBasicAuth +ExportCertData +StrictRequire + + # SSL Protocol Adjustments: + # The safe and default but still SSL/TLS standard compliant shutdown + # approach is that mod_ssl sends the close notify alert but doesn't wait for + # the close notify alert from client. When you need a different shutdown + # approach you can use one of the following variables: + # o ssl-unclean-shutdown: + # This forces an unclean shutdown when the connection is closed, i.e. no + # SSL close notify alert is send or allowed to received. This violates + # the SSL/TLS standard but is needed for some brain-dead browsers. Use + # this when you receive I/O errors because of the standard approach where + # mod_ssl sends the close notify alert. + # o ssl-accurate-shutdown: + # This forces an accurate shutdown when the connection is closed, i.e. a + # SSL close notify alert is send and mod_ssl waits for the close notify + # alert of the client. This is 100% SSL/TLS standard compliant, but in + # practice often causes hanging connections with brain-dead browsers. Use + # this only for browsers where you know that their SSL implementation + # works correctly. + # Notice: Most problems of broken clients are also related to the HTTP + # keep-alive facility, so you usually additionally want to disable + # keep-alive for those clients, too. Use variable "nokeepalive" for this. + # Similarly, one has to force some clients to use HTTP/1.0 to workaround + # their broken HTTP/1.1 implementation. Use variables "downgrade-1.0" and + # "force-response-1.0" for this. + # BrowserMatch "MSIE [2-6]" \ + # nokeepalive ssl-unclean-shutdown \ + # downgrade-1.0 force-response-1.0 + + # FORCAST modification from base configuration + RewriteEngine on + RewriteCond %{REQUEST_URI} ^/$ + RewriteRule (.*) /src/landing-page/ [R=301,L] + + + Options +ExecCGI -Indexes + AddHandler cgi-script .py + Require all granted + + + AliasMatch "^/download/(.+\.csv)$" "/tmp/$1" + + + Require all granted + + + # End modification + + +# vim: syntax=apache ts=4 sw=4 sts=4 sr noet diff --git a/sites-enabled/000-default.conf b/apache2/sites-enabled/sample/forcast.conf similarity index 100% rename from sites-enabled/000-default.conf rename to apache2/sites-enabled/sample/forcast.conf diff --git a/docker-compose-dev.yaml b/docker-compose-dev.yaml index 7ebb50a0..23fba001 100644 --- a/docker-compose-dev.yaml +++ b/docker-compose-dev.yaml @@ -4,6 +4,7 @@ services: image: ghcr.io/ccmbioinfo/forcast:latest ports: - 80:80 + - 443:443 tmpfs: - /run/apache2 - /run/mongodb @@ -15,7 +16,8 @@ services: - ./jbrowse/data:/var/www/html/jbrowse/data - ./jbrowse/plugins/ColorByCDS:/var/www/html/jbrowse/plugins/ColorByCDS - ./jbrowse/plugins/ExportSequence:/var/www/html/jbrowse/plugins/ExportSequence - - ./sites-enabled:/etc/apache2/sites-enabled + - ./apache2/certs:/etc/apache2/certs + - ./apache2/sites-enabled/forcast-ssl.conf:/etc/apache2/sites-enabled/000-default.conf - ./src:/var/www/html/src - mongodb:/var/lib/mongodb volumes: diff --git a/docker-compose-prod.yaml b/docker-compose-prod.yaml index 68067e67..9c3e1093 100644 --- a/docker-compose-prod.yaml +++ b/docker-compose-prod.yaml @@ -4,6 +4,7 @@ services: image: ghcr.io/ccmbioinfo/forcast:stable ports: - 80:80 + - 443:443 tmpfs: - /run/apache2 - /run/mongodb @@ -15,7 +16,8 @@ services: - ./jbrowse/data:/var/www/html/jbrowse/data - ./jbrowse/plugins/ColorByCDS:/var/www/html/jbrowse/plugins/ColorByCDS - ./jbrowse/plugins/ExportSequence:/var/www/html/jbrowse/plugins/ExportSequence - - ./sites-enabled:/etc/apache2/sites-enabled + - ./apache2/certs:/etc/apache2/certs + - ./apache2/sites-enabled/forcast-ssl.conf:/etc/apache2/sites-enabled/000-default.conf - ./src:/var/www/html/src - mongodb:/var/lib/mongodb volumes: diff --git a/docker-compose.yaml b/docker-compose.yaml index d837cb51..72546851 100644 --- a/docker-compose.yaml +++ b/docker-compose.yaml @@ -16,7 +16,7 @@ services: - ./jbrowse/data:/var/www/html/jbrowse/data - ./jbrowse/plugins/ColorByCDS:/var/www/html/jbrowse/plugins/ColorByCDS - ./jbrowse/plugins/ExportSequence:/var/www/html/jbrowse/plugins/ExportSequence - - ./sites-enabled:/etc/apache2/sites-enabled + - ./apache2/sites-enabled/forcast.conf:/etc/apache2/sites-enabled/000-default.conf - ./src:/var/www/html/src - mongodb:/var/lib/mongodb volumes: diff --git a/jbrowse/data/datasets.sample.conf b/jbrowse/data/datasets.sample.conf index cca4f991..4eb97902 100644 --- a/jbrowse/data/datasets.sample.conf +++ b/jbrowse/data/datasets.sample.conf @@ -1,2 +1,2 @@ -# This configuration file is user-editable and is mounted as a volume inside docker-compose.yaml; +# This configuration file is user-editable and is mounted as a volume inside docker-compose.yaml, docker-compose-dev.yaml, and docker-compose-prod.yaml; # in addition, it is merged with the JBrowse main configuration file (jbrowse.conf) through an include statement.