This section describes how to configure the
When running with the
varfish-docker-compose files and the provided database files, VarFish comes preconfigured with sensible default settings and also contains some example datasets to try out.
There are a few things that you might want to tweak.
Please note that there might be more settings that you can change when exploring the VarFish source code but right now their use is not supported for external users.
TLS / SSL Configuration¶
docker-compose.yml file you will find sections starting with
# BEGIN and are followed by a token, e.g.,
You will have to decide for one of the following and make sure that the lines for your choice are not commented out while all the others should be (in the case of
OR leave the section in for all
varfish-docker-compose setup uses traefik as a reverse proxy and must be reconfigured if you want to change the default behaviour of using self-signed certificates.
By default (and as a fallback), traefik will use self-signed certificates that are recreated at every startup. These are probably fine for a test environment but you might want to change this to one of the below.
You can provide your own certificates by placing them into
server.key. Make sure to provide the full certificate chain if needed (e.g., for DFN issued certificates).
If your site is reachable from the internet then you can also use
settings:production-letsencryptwhich will use [letsencrypt](https://letsencrypt.org/) to obtain the certificates. NB: if you make your site reachable from the internet then you should be aware of the implications. VarFish is MIT licensed software which means that it comes “without any warranty of any kind”, see the
LICENSEfile for details.
After changing the configuration, restart the site (e.g., with
docker-compose down && docker-compose up -d if it is running in detached mode).
VarFish can be configured to use up to two upstream LDAP servers (e.g., OpenLDAP or Microsoft Active Directory).
For this, you have to set the following environment variables in the file
.env in your
varfish-docker-compose checkout and restart the site.
The variables are given with their default values.
Enable primary LDAP authentication server (values:
URI for primary LDAP server (e.g.,
Distinguished name (DN) to use for binding to the LDAP server.
Password to use for binding to the LDAP server.
DN to use for the search base, e.g.,
Domain to use for user names, e.g. with
EXAMPLEusers from this domain can login with
Domain used for printing the user name.
If you have the first LDAP configured then you can also enable the second one and configure it.
Enable secondary LDAP authentication server (values:
The remaining variable names are derived from the ones of the primary server but using the prefix
AUTH_LDAP2 instead of
Sending of Emails¶
You can configure VarFish to send out emails, e.g., when permissions are granted to users.
Enable sending of emails.
String to use for the sender, e.g.,
Prefix to use for email subjects, e.g.,
URL to the SMTP server to use, e.g.,
External Postgres Server¶
In some setups, it might make sense to run your own Postgres server. The most common use case would be that you want to run VarFish in a setting where fast disks are not available (virtual machines or in a “cloud” setting). You might still have a dedicated, fast Postgres server running (or available as a service from your cloud provider). In this case, you can configure the database connection settings as follows.
Adjust to the credentials, server, and database name that you want to use.
The default settings do not make for secure settings in the general case.
However, Docker Compose will create a private network that is only available to the Docker containers.
In the default
docker-compose setup, postgres server is thus not exposed to the outside and only reachable by the VarFish web server and queue workers.
Text to display on the login page.
Key to use for encrypting secrets in the database (such as saved public keys for the Beacon Site feature). You can generate such a key with the following command:
python -c 'import os, base64; print(base64.urlsafe_b64encode(os.urandom(32)))'.
Sentry is a service for monitoring web apps. Their open source version can be installed on premise. You can configure sentry support as follows
Enable Sentry support.
A sentry DSN to report to. See Sentry documentation for details.
System and Docker (Compose) Tweaks¶
A number of customizations customizations of the installation can be done using Docker or Docker Compose. Other customizations have to be done on the system level. This section lists those that the authors are aware of but in particular network-related settings can be done on many levels.
Using Non-Default HTTP(S) Ports¶
If you want to use non-standard HTTP and HTTPS ports (defaults are 80 and 443) then you can tweak this in the
traefik container section.
You have to adjust two parts.
ports: - "80:80" - "443:443"
To listen on ports
8443 instead, adjust this to:
Also, you have to change the command line arguments to traefik for the
web (HTTP) and
websecure (HTTPS) entrypoints.
- "--entrypoints.web.address=:80" - "--entrypoints.websecure.address=:443"
Change the lines to read:
- "--entrypoints.web.address=:8080" - "--entrypoints.websecure.address=:8443"
Then, restart by calling
docker-compose up -d in the directory with the
Listing on Specific IPs¶
By default, the
traefik container will listen on all IPs and interfaces of the host machine.
You can change this by prefixing the
ports list with the IPs to listen on.
Change following lines to read:
ports: - "80:80" - "443:443"
To the following to only listen on
ports: - "10.0.0.1:80:80" - "10.0.0.1:443:443"
More details can be found in the corresponding section of the Docker Compose manual.
Of course, you can combine this with adjusting the ports, e.g., to
Limit Incoming Traffic¶
In some settings you might want to limit incoming traffic to certain networks / IP ranges.
In principle, this is possible with adjusting the Traefik load balancer/reverse proxy.
However, we would recommend you to use the firewall of your operating system or your overall network for this purpose.
Consult the corresponding manual (e.g., of
firewalld for CentOS/Red Hat or of
ufw for Debian/Ubuntu) for instructions.
We remark that in most cases it is better to perform an actual separation of networks and place each (virtual) machine into one network only.
volumes sub directory of the
varfish-docker-compose directory contains the data for the containers.
These are as follows.
Databases for variant annotation with CADD (large).
Databases for variant prioritization (medium)
Transcript databases for annotation (small).
Storage for files uploaded from client via REST API (big).
PostgreSQL databases (very big).
Storage for the work queues (small).
Configuration and certificates for load balancer (very small).
In principle, you can put these on different storages systems (e.g., some over the network and some on directly attached disks).
The main motivation is that fast storage is expensive.
Putting the small and medium sized directories on slower, cheaper storage will have little or no effect on storage efficiency.
At the same time, access to
exomiser directories should be fast.
postgres, this storage is accessed most heavily and should be on storage as fast as you can afford.
cadd-rest-api should also be on fast storage but it is accessed almost only read-only.
You can put the
minio folder on slower storage to shave off some storage costs from your VarFish installation.
You can put
minioon cheaper storage.
cadd-rest-api, you can probably get away to put this on cheaper storage.
Put everything else, in particular
postgreson storage as fast as you can afford.
As described in the section Performance Tuning, the authors recommend using an advanced file system such as ZFS on multiple SSDs for large, fast storage and enabling compression. You will get excellent performance and can expect storage saving of 50%.
Beacon Site (Experimental)¶
An experimental support for the GA4GH beacon protocol.
Whether or not to enable experimental beacon site support.
The following list remains a points to implement with Docker Compose and document.
Updating Extras Data