10 Configuration

IQdesktop is configured using a simple configuration file. This file contains information, such as:

  • Which image to run
  • Shared volumes between host computer and IQdesktop
  • User name of user to be created inside IQdesktop
  • Initial password of user
  • User ID
  • Port-mapping for connection (VNC and SSH)
  • License keys for some of the software tools can be conveniently passed via the config file (if available)
  • Etc.

10.1 Default config file

Below you can see the contents of a default config file that will work (as is) on Windows. The only requirement for working “as is” is that a folder C:\IQDESKTOP exists on your local Windows machine. More about that in the following documentation of the configuration file - inline comments explain what the settings mean and how you can change them.

Don’t get scared, configuration is easy. Almost all text in the following box is documentation and to get it to run the first time on Windows you do not need to change anything!

Copy the contents of the following box to a text file (e.g. my-iqdesktop-config.yml), edit as needed, and save it.

!!Use a text editor like Notepad++, VSCODE, or ATOM for creation and editing of this configuration file - or any other editor that allows saving the file UTF-8 encoded!!

version: '2.4'
services:
  IQdesktop:
  
    # Define the image version to run "latest" might need to be replaced, 
    # depending on which version you have downloaded from Docker Hub with the 
    # "docker pull" command
    image: intiquan/iqdesktop:latest
  
    # Naming - you should keep it as is
    hostname: IQdesktop
  
    # Set MAC address as needed (keep on default if unsure what you need it for)
    mac_address: 00:00:28:06:19:71     
  
    # Shared memory. 2gb is reasonable - keep as is
    shm_size: '2gb'
    
    # Define the number of cores to which your IQdesktop container should have 
    # access. On Windows you can safely remove this line as the docker-desktop 
    # software allows these settings. On non-Windows systems it should be set.
    cpus: 4

    # Define the amount of memory to which your IQdesktop container should have
    # access. On Windows you can safely remove this line as the docker-desktop 
    # software allows these settings. On non-Windows systems it should be set.
    mem_limit: "8gb"
    
    # Define the folder on the host computer to be mapped to the /IQDESKTOP/SHARE
    # folder within the IQdesktop container. Here an example for Windows is made.
    # You can change "C:\IQDESKTOP" to something else if desired. For Mac and 
    # Linux host systems you also need to change "C:\IQDESKTOP" to a path on your 
    # host system. Note that the contents of this folder will then be available 
    # within IQDESKTOP within /IQDESKTOP/SHARE. In theory you can add additional 
    # shared volumes by adding additional lines.
    # IMPORTANT: The folder on your local computer (here in this example "C:\IQDESKTOP")
    # needs to exist. Otherwise the container will not start and you will see an 
    # error message.
    # IMPORTANT2: On Windows you can only share local harddrives (not mounted 
    # network drives).On Linux and MacOS that limitation does not exist.
    volumes:
      - C:\IQDESKTOP:/IQDESKTOP/SHARE
      
    # Define port mapping. On single user host systems nothing needs to be changed.
    # On multi-user host systems each IQdesktop container needs to have a unique 
    # external port mapping. Ports 5901, 22, and 3838 are used internally in 
    # IQdesktop for VNC, SSH,  and Shiny, respectively. Access from outside of 
    # the container to these services is pre-configured to ports 5900, 6900, 
    # and 7900, respectively.
    ports:
      - "5900:5901"   # VNC port mapping
      - "6900:22"     # SSH port mapping
      - "7900:3838"   # Shiny-server port mapping

    # In the case that you would like to mount other filesystems directly into the
    # IQdesktop container (e.g. AWS S3 buckets, CIFS/SMB, etc.) you will need to 
    # set the following argument to "true".
    privileged: true
    
    environment:
    
      # Define the name of your organization
      # Public version: does nothing at all
      # Controlled version: Will be displayed e.g. in xterm and can be used for 
      # licensing - per organization rather than per user
      - ORGANIZATION=Hello World Organization!
      
      # Licensekey for IQdesktop.
      # Public version: No impact - no license key needed
      # Controlled version: Add the licensekey you obtained from IntiQuan
      - LICENSEKEY=This is not a license key - but you can add one here!

      # Set your timezone to allow correct display of time. You can find valid 
      # entries for this field here: 
      # https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
      - TIMEZONE=Europe/Zurich
    
      # Set your desired username that you would like to use in IQdesktop
      # You ideally want to change this field. A good setting is the username 
      # that you already use on your local computer
      - USER=user
      
      # Set your initial password. This password is used for both SSH and VNC 
      # connections. Since this password is written down in the config file it 
      # is not secret and should be changed once logged in the first time to 
      # IQdesktop. More about that in the "Using IQdesktop" part of the 
      # documentation.
      - PASSWORD=password
      
      # Numerical user ID. No meaning on Windows - so you can keep it on default.
      # On Mac set it to: 501. On multi-user systems your Sysadmin will have his 
      # or her own opinion and set it for you. In any case it is the user ID of 
      # the user within IQdesktop. When allowing for shared volumes this is also 
      # the user ID with which files on the host system are accessed.
      - USER_ID=1002
  
      # You can define if your user in IQdesktop should have sudo rights or not.
      # You decide for yourself by setting "true" or "false". On multi-user
      # systems in production the Sysadmin will likely set a "false" here for you.
      - ALLOW_SUDO=false    
    
      # When running IQdesktop on multiple different host systems at the same 
      # time it can be interesting to check on which host a particular container
      # is running. For this you can provide a host ID here. This information is 
      # purely informative in nature and displayed when opening a terminal in 
      # IQdesktop or executing the terminal command "version". When running 
      # IQdesktop on your local computer the default is fine.
      - HOST_ID=Local Computer
      
      # Define the OS type of your host machine (on which docker is running). 
      # Possible options are: "linux", "windows", "unknown". Leaving the definition
      # empty is the same as setting "unknown". This is only used to determine
      # if mounting of external file systems is possible. If "windows" it is not
      # possible (with exception of AWS S3). For the purpose here "unknown" will
      # lead to the same behavior as "windows". If you have a Mac then choose 
      # "linux".
      - HOST_OS=  

      # IQdesktop comes with two themes - one dark and one light. Choose your 
      # preference by defining "dark" or "light" below.
      - THEME=light
      
      # IQdesktop allows access to the container via SSH if the following is set
      # to "true". If you do not need SSH then set it to "false"
      - SSH_SERVER=true
      
      # Shiny is a cool thing but Shiny-servers are sometimes annoying to set up
      # and maintain. In order to allow easy deployment of Shiny-apps and sharing 
      # of results with colleagues IQdesktop contains a Shiny-server that can be 
      # started and stopped with a Play/Stop button. More information about that 
      # in the part "Using IQdesktop" of the documentation. You also can define 
      # here in the config file if this feature should be enabled "true" or 
      # disabled "false". By default it is enabled and only on multi-user systems 
      # the Sysadmin might decide differently.
      - ALLOW_SHINY_SERVER=true  
      
      # If you use IQdesktop on your local computer you can safely ignore the 
      # next two options. If you access IQdesktop remotely via VPN you can ignore 
      # them as well. If, however, you access IQdesktop remotely via an unsecured 
      # connection you might want to consider securing the connection with a 
      # certificate based approach. The relevant certificate information will be 
      # added here below in the two fields. More information about this is 
      # available in part "Accessing IQdesktop" of this documentation and 
      # also explaining how you can generate your own certificates.
      # Note that private keys and certificates are typically multi line text files.
      # Here this information needs to be entered as single lines using "\n" 
      # instead of a line break.
      - VNC_PRIVATE_KEY=
      - VNC_CERTIFICATE=
      
      # Some of the software packages available in IQdesktop require license keys. 
      # These can conveniently be defined already in this configuration file. 
      - NONMEM_LICENSE_KEY=The contents of the nonmem.lic file
      - MONOLIX_LICENSE_KEY=Monolix cloud licenses can be added here
      - 'MATLAB_LICENSE_FILE=MATLAB lic file here - single line - single quotes needed'
      # If not provided in license file then the following options exist:
      # MONOLIX: You can provide your activation key when you start MONOLIX in 
      #          IQdesktop and it asks for it. You only need to do this once
      #          after the start of an IQdesktop container.  
      # NONMEM: Install the license key from the IQdesktop command line with the 
      #         command: 'nmlicense'. You only need to do this once
      #         after the start of an IQdesktop container.
      # MATLAB: Start MATLAB - it will ask you to log in with your Mathworks account.
      #         Select your license and activate it. You only need to do this once
      #         after the start of an IQdesktop container.
      
      # License key for IQReport can be provided here. The one below will work
      # with the default config file. If you need your own license keys - please
      # contact info@intiquan.com. Keys are free for academia, non-profit, 
      # governmental use.
      - IQREPORT_LICENSE_KEY=7C8D1604-B44B1092-49516465736B746F702044656D6F-B87451D-9DE9055A

      # Finally, some settings for IQR Tools and IQReport. The "compliance mode" 
      # in IQR Tools allows to automatically generate traceability information 
      # when conducting an analysis. You can enable it by setting 
      # "IQRTOOLS_COMPLIANCE=true". More info about it on https://iqrtools.intiquan.com.
      # IQReport is the Word reporting tool from IntiQuan. The option 
      # "IQREPORT_TEMPLATE" allows to activate specific Word templates to be used
      # in IQdesktop. Keep it as is, which will give you access to the Default 
      # template. If you are interested in being able to autogenerate Word reports 
      # in your organizations Word Style ... we could make that happen and then
      # you can define here the identifier for your specific template.
      - IQRTOOLS_COMPLIANCE=false
      - IQREPORT_TEMPLATE=
      
      # AWS keys. Provision of AWS keys in the config file allows quick and easy 
      # mounting of AWS S3 buckets. If you feel uncomfortable to provide the 
      # AWS keys in the config file you can also provide them inside the container 
      # using the command "awskeys".
      - AWS_ACCESS_KEY_ID=
      - AWS_SECRET_ACCESS_KEY=
      

      # When mounting CIFS/SMB/Samba drives it can be decided if the full path
      # is implemented in the MOUNT folder or only the basename of the folder
      # path on the remote server. "false" and "true" are valid values.
      - MOUNT_BASENAME=true
      
      # Define mount points (up to 5 are possible) CIFS/SMB/Samba 
      # IMPORTANT: Only works on a Linux host machine. On Windows host machines 
      # it is NOT working!
      # MOUNT_n_LABEL: should be a single word to identify the mount point. 
      #                Example "projects"
      # MOUNT_n_SERVER_IP: is the server address with "\\" or "//", etc. 
      #                Example "192.168.5.93"
      # MOUNT_n_SERVER_FOLDER: is the folder path on the server to be mounted,
      #                        without leading or trailing "/" or "\". 
      #                        Example "projects/ABC123"
      # MOUNT_n_OPTIONS: Optional setting of cifs mount options. If not provided, 
      #                  it will be set to: 'vers=1.0,username=%USER%,noauto,user' 
      #                  where %USER will be replaced by the USER name defined 
      #                  in this config file.
      # Below examples are provided
      - MOUNT_1_LABEL=projects
      - MOUNT_1_SERVER_IP=192.168.5.93
      - MOUNT_1_SERVER_FOLDER=projects/ABC123
      - MOUNT_1_OPTIONS=vers=1.0,username=differentuser,noauto,user

      - MOUNT_2_LABEL=
      - MOUNT_2_SERVER_IP=
      - MOUNT_2_SERVER_FOLDER=
      - MOUNT_2_OPTIONS=
      
      - MOUNT_3_LABEL=
      - MOUNT_3_SERVER_IP=
      - MOUNT_3_SERVER_FOLDER=
      - MOUNT_3_OPTIONS=
      
      - MOUNT_4_LABEL=
      - MOUNT_4_SERVER_IP=
      - MOUNT_4_SERVER_FOLDER=
      - MOUNT_4_OPTIONS=
      
      - MOUNT_5_LABEL=
      - MOUNT_5_SERVER_IP=
      - MOUNT_5_SERVER_FOLDER=
      - MOUNT_5_OPTIONS=

10.2 Server

On a multi-user system a web-based interface is useful to have, which essentially populates information in individual config files based on a templating system. Read more about this in Multi User Environment.

10.3 Cloud

Handling can be similar to local computer or server, depending on the setup of the cloud. Your Sysadmin should know more.