Configuration ============= The file **MICA_HOME/conf/application-prod.yml** is to be edited to match your server needs. This file is written in YAML format allowing to specify a hierarchy within the configuration keys. The YAML format uses indentations to express the different levels of this hierarchy. The file is already pre-filled with default values (to be modified to match your configuration), just be aware that you should not modify the indentations. In the following documentation, the configuration keys will be presented using the dot-notation (levels are separated by dots) for readability. HTTP Server Configuration ------------------------- Mica server is a web application and as such, you need to specify on which ports the web server should listen to incoming requests. ========================= ================== Property Description ========================= ================== ``server.port`` HTTP port number. Generally speaking this port should not be exposed to the web. Use the https port instead. ``server.host`` Web server host name. ``server.context-path`` The URL's context path, starting with a `/`. For instance when setting `/repo`, the base URL will be `https://example.org/repo`. ``https.port`` HTTPS port number. ========================= ================== MongoDB Server Configuration ---------------------------- Mica server will store its data (system configuration, networks, studies, datasets, etc.) in a MongoDB database. You must specify how to connect to this database. =========================== =========================== Property Description =========================== =========================== ``spring.data.mongodb.uri`` MongoDB URI. `Read Standard Connection `_ String Format to learn more. =========================== =========================== By default MongoDB does not require any user name, it is highly recommended to configure the database with a user. This can be done by enabling the Client Access Control procedure. Follow these steps to enable the Client Access Control on your server: * create a user with the proper roles on the target databases * restart the MongoDB service with Client Access Control enabled .. note:: Once the MongoDB service runs with Client Access Control enabled, all database connections require authentication. **MongoDB User Creation Example** The example below creates the *micaadmin* user for *mica* database: .. code-block:: javascript use admin db.createUser( { user: "micaadmin", pwd: "micaadmin", roles: [ { "role" : "readWrite", "db" : "mica" }, { "role" : "dbAdmin", "db" : "mica" }, { "role" : "readAnyDatabase", "db": "admin" } ] }); Here is the required configuration snippet in **/etc/mica/application-prod.yml** for the above user: .. code-block:: yaml spring: data: mongodb: uri: mongodb://micaadmin:micaadmin@localhost:27017/mica?authSource=admin .. note:: Mica requires either **clusterMonitor** or **readAnyDatabase** role on the *admin* database for validation operations. The first role is useful for a cluster setup and the latter if your MongoDB is on a single server. Opal Server Configuration ------------------------- Mica server uses Opal to retrieve data dictionaries, data summaries and variable taxonomies. This server is sometimes referred as the Opal primary server (secondary servers can be defined at study level). If you want to publish datasets, the following Opal connection details needs to be configured. ================= ================================================================ Property Description ================= ================================================================ ``opal.url`` Opal server URL. It is highly recommended to use https protocol. ``opal.username`` User name for connection to Opal server. ``opal.password`` User password for connection to Opal server. ``opal.token`` `Opal personal access token `_ for connection to Opal server. If defined it has the priority over the username/password credentials. ================= ================================================================ Mica server should connect to Opal and access to some selected tables only with the lowest level of permissions (View dictionary and summary, i.e. no access to individual data). Please refer to the Opal Table Documentation for more details about the permissions that can be applied on a table. Agate Server Configuration -------------------------- Mica server uses Agate as a user directory and as a notification emails service. From the Agate point of view, Mica is not a user: it is an application. Each time Mica needs a service from Agate, it will provide the information necessary to its identification. The application credentials registered in Mica are to be specified in this section. If you want to specify advanced permissions or allow users to submit data access requests, the following Mica connection details needs to be configured. ========================== ================================================================ Property Description ========================== ================================================================ ``agate.url`` Agate server URL. It is highly recommended to use https protocol. ``agate.application.name`` Mica application ID for connection to Agate server. ``agate.application.key`` Mica application key for connection to Agate server. ========================== ================================================================ Cross Site Resource Forgery (CSRF) ---------------------------------- `CSRF `_ attacks can be mitigated by a built-in interceptor. Default behavior allows connections (http or https) from ``localhost`` and ``127.0.0.1``. Requests from pages served by Mica should be allowed as well (https only), unless network settings or proxies modify or do not report the referer URL. ======================================= ========================================================================= Property Description ======================================= ========================================================================= ``csrf.allowed`` Comma separated list of client ``host:port`` explicitly allowed to connect to Opal server. Use ``*`` as a wildcard. Default is empty. ======================================= ========================================================================= Shiro Configuration ------------------- `Shiro `_ is the authentication and authorization framework used by Mica. There is a minimum advanced configuration that can be applied to specify how Shiro will hash the password. In practice this only applies to the users defined in the shiro.ini file. Default configuration is usually enough. =================================== ================================ Property Description =================================== ================================ ``shiro.password.nbHashIterations`` Number of re-hash operations. ``shiro.password.salt`` Salt to be applied to the hash. =================================== ================================ Elasticsearch Configuration --------------------------- Mica server uses `Elasticsearch `_ as its search engine. Elasticsearch is a key functionality of Mica as the process of publication consist in indexing documents (networks, studies, variables etc.) in the search engine. Advanced queries can be applied on the published documents. .. note:: Since the upgrade to Java 21, Mica no longer supports embedded Elasticsearch. An external Elasticsearch server is required. As of now, Mica uses Elasticsearch 8.16.1 or compatible versions. Alternatively, Mica also supports `OpenSearch 2.x `_ through the `mica-search-os2 plugin `_, which provides a drop-in replacement for the default Elasticsearch integration. See the :doc:`plugins` page for more information on search plugins and how to switch between Elasticsearch and OpenSearch. The configuration below specifies how Mica should connect to the Elasticsearch server. ================================================== ================================ Property Description ================================================== ================================ ``elasticsearch.host`` Elasticsearch server host address. Defaults to ``localhost``. ``elasticsearch.port`` Elasticsearch server port. Defaults to ``9200``. ``elasticsearch.clusterName`` Cluster identifier. ``elasticsearch.shards`` Number of shards. ``elasticsearch.replicas`` Number of replicas. ``elasticsearch.maxConcurrentJoinQueries`` Maximum count of ES queries that can be executed concurrently. Default value is ``4``. ``elasticsearch.concurrentJoinQueriesWaitTimeout`` Wait timeout when executing concurrent ES queries in millis. Default value is ``30000`` milliseconds. ================================================== ================================ **Elasticsearch Cluster** Mica connects to an external Elasticsearch server or cluster. You need to configure the connection details to point to your Elasticsearch installation. .. note:: As of now, the supported version of Elasticsearch is `8.16.1 `_ or compatible versions. Example configuration to connect to a single Elasticsearch server: .. code-block:: yaml elasticsearch: host: localhost port: 9200 clusterName: mica Example configuration to connect to an Elasticsearch cluster: .. code-block:: yaml elasticsearch: host: es-node1.example.com port: 9200 clusterName: mycluster **Elasticsearch Server Configuration** Elasticsearch should be installed and running before starting Mica. See the `Elasticsearch installation guide `_ for installation instructions. For Docker-based installations, refer to the :doc:`installation` guide which includes a complete docker-compose configuration with Elasticsearch. **Docker Elasticsearch Configuration Example** For a single-node Elasticsearch setup using Docker, use the following configuration: .. code-block:: yaml es8: image: docker.elastic.co/elasticsearch/elasticsearch:8.16.1 expose: - 9300 - 9200 environment: - cluster.name=mica - node.name=es8 - discovery.type=single-node - bootstrap.memory_lock=true - network.host=0.0.0.0 - xpack.security.enabled=false - xpack.security.http.ssl.enabled=false - "ES_JAVA_OPTS=-Xms512m -Xmx512m" ulimits: memlock: soft: -1 hard: -1 **Important Configuration Notes:** - ``xpack.security.enabled=false`` disables X-Pack security features (not recommended for production without proper network security) - ``discovery.type=single-node`` configures Elasticsearch for single-node operation - ``ES_JAVA_OPTS`` sets JVM heap size (adjust based on your available memory) - Ensure that the Elasticsearch cluster name in your Elasticsearch configuration matches the ``elasticsearch.clusterName`` setting in Mica's configuration Miscelaneous Configuration -------------------------- Advanced settings. =================================== ================================ Property Description =================================== ================================ ``dar.reminder.cron`` Schedule (cron syntax) of the email reminder for Data Access report. Default value is ``0 0 0 * * ?`` (every day at midnight). ``sets.cleanup.cron`` Schedule (cron syntax) of the expired cart/sets cleanup. Default value is ``0 0 * * * ?`` (every hour). =================================== ================================ User Directories ---------------- The security framework that is used by Mica for authentication, authorization etc. is `Shiro `_. Configuring Shiro for Mica is done via the file **MICA_HOME/conf/shiro.ini**. See also `Shiro ini file documentation `_. .. note:: Default configuration is a static user 'administrator' with password 'password' (or the one provided while installing Mica Debian/RPM package). By default Mica server has several built-in user directories (in the world of Shiro, a user directory is called a realm): * a file-based user directory (**shiro.ini** file), * the user directory provided by Agate. Although it is possible to register some additional user directories, this practice is not recommended as Agate provides more than a service of authentication (user profile, notification emails etc.). In the world of Shiro, a user directory is called a *realm*. **File Based User Directory** The file-based user directory configuration file **MICA_HOME/conf/shiro.ini**. .. note:: It is not recommended to use this file-based user directory. It is mainly dedicated to define a default system super-user and a password for the anonymous user. For a better security, user passwords are encrypted with a one way hash such as sha256. The example shiro.ini file below demonstrates how encryption is configured. .. code-block:: bash # ======================= # Shiro INI configuration # ======================= [main] # Objects and their properties are defined here, # Such as the securityManager, Realms and anything else needed to build the SecurityManager [users] # The 'users' section is for simple deployments # when you only need a small number of statically-defined set of User accounts. # # Password here must be encrypted! # Use shiro-hasher tools to encrypt your passwords: # DEBIAN: # cd /usr/share/mica2/tools && ./shiro-hasher -p # UNIX: # cd /tools && ./shiro-hasher -p # WINDOWS: # cd /tools && shiro-hasher.bat -p # # Format is: # username="password-hash"[,role]* administrator = "$shiro2$argon2id$v=19$t=1,m=65536,p=4$q4uNaPW6sY1mDaLvlRcXPw$/zeLc6+GYP9//fahi+8qDj/a1KlJLvtQjRRTvbOePb0",mica-administrator anonymous = "$shiro2$argon2id$v=19$t=1,m=65536,p=4$2ikVjnBLc7hjLWh1+Za/Uw$hgaMknQwQOcEy2kYYOgKLloSRo2VvHbYbxASNu69wuk" [roles] # The 'roles' section is for simple deployments # when you only need a small number of statically-defined roles. # Format is: # role=permission[,permission]* mica-administrator = * Passwords must be encrypted using shiro-hasher tools (included in Mica tools directory): .. code-block:: bash cd /usr/share/mica2/tools ./shiro-hasher -p Reverse Proxy Configuration --------------------------- Mica server can be accessed through a reverse proxy server. **Apache** Example of Apache directives that: * redirects HTTP connection on port 80 to HTTPS connection on port 443, * specifies acceptable protocols and cipher suites, * refines organization's specific certificate and private key. .. code-block:: text ServerName mica.your-organization.org ProxyRequests Off ProxyPreserveHost On Order deny,allow Allow from all RewriteEngine on ReWriteCond %{SERVER_PORT} !^443$ RewriteRule ^/(.*) https://mica.your-organization.org:443/$1 [NC,R,L] ServerName mica.your-organization.org SSLProxyEngine on SSLEngine on SSLProtocol All -SSLv2 -SSLv3 SSLHonorCipherOrder on # Prefer PFS, allow TLS, avoid SSL, for IE8 on XP still allow 3DES SSLCipherSuite "EECDH+ECDSA+AESGCM EECDH+aRSA+AESGCM EECDH+ECDSA+SHA384 EECDH+ECDSA+SHA256 EECDH+aRSA+SHA384 EECDH+aRSA+SHA256 EECDH+AESG CM EECDH EDH+AESGCM EDH+aRSA HIGH !MEDIUM !LOW !aNULL !eNULL !LOW !RC4 !MD5 !EXP !PSK !SRP !DSS" # Prevent CRIME/BREACH compression attacks SSLCompression Off SSLCertificateFile /etc/apache2/ssl/cert/your-organization.org.crt SSLCertificateKeyFile /etc/apache2/ssl/private/your-organization.org.key ProxyRequests Off ProxyPreserveHost On ProxyPass / https://localhost:8445/ ProxyPassReverse / https://localhost:8445/ For performance, you can also activate Apache's compression module (mod_deflate) with the following settings (note the json content type setting) in file */etc/apache2/mods-available/deflate.conf*: .. code-block:: text # these are known to be safe with MSIE 6 AddOutputFilterByType DEFLATE text/html text/plain text/xml # everything else may cause problems with MSIE 6 AddOutputFilterByType DEFLATE text/css AddOutputFilterByType DEFLATE application/x-javascript application/javascript application/ecmascript AddOutputFilterByType DEFLATE application/rss+xml AddOutputFilterByType DEFLATE application/xml AddOutputFilterByType DEFLATE application/json Recommended security headers are (to be added to the ``apache2.conf`` file, requires ``headers`` module): .. code-block:: text # Security Headers, see https://securityheaders.com/ Header set Strict-Transport-Security "max-age=63072000" Header set X-Frame-Options DENY Header set X-XSS-Protection 1;mode=block Header set X-Content-Type-Options nosniff Header set Content-Security-Policy "frame-ancestors 'none'" Header set Referrer-Policy "same-origin" Header set Permissions-Policy "fullscreen=(self)" Header onsuccess edit Set-Cookie ^(.+)$ "$1;HttpOnly;Secure;SameSite=Strict"