configuration.ttl

@prefix ldh:    <https://w3id.org/atomgraph/linkeddatahub#> .
@prefix rdf:    <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix dh:     <https://www.w3.org/ns/ldt/document-hierarchy#> .
@prefix dct:    <http://purl.org/dc/terms/> .

<> a dh:Item ;
    dct:title "Configuration" ;
    dct:description "Overview of configuration options" ;
    rdf:_1 <#content> .

<#content> a ldh:XHTML ;
    rdf:value """<div xmlns="http://www.w3.org/1999/xhtml">
    <p class="lead">Overview of configuration options</p>
    <p>LinkedDataHub is configured using environment variables in the <samp>docker-compose.yml</samp> file (environment-specific configuration should go into <samp>docker-compose.override.yml</samp> instead).</p>
    <p>Below you'll find a list of environment variables and secrets grouped by service (they are defined in the <samp>environment</samp> sections in <samp>docker-compose.yml</samp>).</p>
    <div>
        <h2 id="config-files">Configuration files</h2>
        <p>LinkedDataHub uses two main RDF configuration files that define dataspaces and services:</p>
        <dl>
            <dt><samp>config/dataspaces.trig</samp></dt>
            <dd>Contains application metadata for each dataspace, including:</dd>
            <dd>
                <ul>
                    <li>Base URIs and application origins</li>
                    <li>Application titles and descriptions</li>
                    <li>Associated ontologies</li>
                    <li>Custom stylesheets</li>
                </ul>
            </dd>
            <dd>This file contains public-facing metadata and can be safely shared.</dd>
            <dt><samp>config/system.trig</samp></dt>
            <dd>Contains internal deployment wiring, including:</dd>
            <dd>
                <ul>
                    <li>Application-to-service bindings (admin and end-user roles)</li>
                    <li>SPARQL endpoint URLs</li>
                    <li>Graph Store Protocol endpoints</li>
                </ul>
            </dd>
            <dd>This file contains internal configuration and is not intended for public sharing, but does not contain credentials.</dd>
            <dt><samp>secrets/credentials.trig</samp></dt>
            <dd>Optional file containing service authentication credentials, including:</dd>
            <dd>
                <ul>
                    <li>Bearer tokens (<code>a:authToken</code>)</li>
                    <li>HTTP Basic auth credentials (<code>a:authUser</code>, <code>a:authPwd</code>)</li>
                </ul>
            </dd>
            <dd>This file is gitignored and must not be committed to version control. See the <samp>credentials</samp> secret entry below for configuration details.</dd>
        </dl>
        <p>All files are in TriG format and are mounted into the LinkedDataHub container at startup. The separation allows you to version control
        dataspace metadata and service wiring while keeping credentials out of version control entirely.</p>
    </div>
    <div>
        <h2 id="service-configuration">Service configuration</h2>
        <p>SPARQL service endpoints are configured in <samp>config/system.trig</samp>. See <a href="../triplestores/#service-configuration">service configuration</a> in the triplestores reference for the RDF properties and examples, and the <a href="../dataspace/#services">dataspace reference</a> for the conceptual overview.</p>
    </div>
    <div>
        <h2 id="linkeddatahub">linkeddatahub</h2>
        <div>
            <h3 id="secrets">Secrets</h3>
            <dl>
                <dt><samp>owner_cert_password</samp></dt>
                <dd>Password of the owner's WebID certificate</dd>
                <dt><samp>secretary_cert_password</samp></dt>
                <dd>Password of the secretary's WebID certificate</dd>
                <dt><samp>client_truststore_password</samp></dt>
                <dd>Password of the client truststore</dd>
                <dt><samp>google_client_id</samp></dt>
                <dd><a href="https://developers.google.com/identity/gsi/web/guides/get-google-api-clientid">OAuth client ID</a></dd>
                <dd><a href="../../get-started/get-an-account/">Login with Google</a> authentication is enabled when this value is provided</dd>
                <dt><samp>google_client_secret</samp></dt>
                <dd><a href="https://developers.google.com/identity/gsi/web/guides/get-google-api-clientid">OAuth client secret</a></dd>
                <dt><samp>orcid_client_id</samp></dt>
                <dd><a href="https://info.orcid.org/documentation/integration-guide/registering-a-public-api-client/">ORCID OpenID Connect client ID</a></dd>
                <dd><a href="../../get-started/get-an-account/">Login with ORCID</a> authentication is enabled when this value is provided</dd>
                <dt><samp>orcid_client_secret</samp></dt>
                <dd><a href="https://info.orcid.org/documentation/integration-guide/registering-a-public-api-client/">ORCID OpenID Connect client secret</a></dd>
                <dt><samp>credentials</samp></dt>
                <dd>RDF dataset file (<samp>./secrets/credentials.trig</samp>) containing service authentication credentials (optional)</dd>
                <dd>Supports HTTP Basic authentication (<code>a:authUser</code>, <code>a:authPwd</code>) and Bearer token authentication (<code>a:authToken</code>)</dd>
                <dd>See <a href="../triplestores/#authentication">authentication</a> in the triplestores reference for RDF examples</dd>
            </dl>
        </div>
        <div>
            <h3 id="webid-auth">WebID authentication</h3>
            <dl>
                <dt><samp>ENABLE_WEBID_SIGNUP</samp></dt>
                <dd><samp>false</samp> to disable. Enabled by default.</dd>
                <dd><em>Currently this will only hide the signup button in the UI, without disabling the endpoint</em></dd>
            </dl>
        </div>
        <div>
            <h3 id="email-server">Email server</h3>
            <dl>
                <dt><samp>MAIL_SMTP_HOST</samp></dt>
                <dd>Hostname of the email server</dd>
                <dt><samp>MAIL_SMTP_PORT</samp></dt>
                <dd>Port number of the email server</dd>
                <dt><samp>MAIL_USER</samp></dt>
                <dd>Username</dd>
                <dt><samp>MAIL_PASSWORD</samp></dt>
                <dd>Password (if required)</dd>
            </dl>
        </div>
        <div>
            <h3 id="linked-data">Linked Data</h3>
            <dl>
                <dt><samp>ENABLE_LINKED_DATA_PROXY</samp></dt>
                <dd><samp>false</samp> to disable the <a href="../http-api/#ld-proxy">Linked Data proxy</a> (enabled by default)</dd>
            </dl>
        </div>
        <div>
            <h3 id="http">HTTP(S)</h3>
            <dl>
                <dt><samp>SELF_SIGNED_CERT</samp></dt>
                <dd>Set to false <samp>false</samp> if not using the self-signed <em>server</em> certificate (e.g. using LetsEncrypt certificate instead). Not to be confused with the WebID client certificate.
                    Enabled by default.</dd>
                <dt><samp>MAX_CONTENT_LENGTH</samp></dt>
                <dd>Maximum allowed request body size (<samp>nginx</samp> has a separate setting for this.) By default <samp>2097152</samp>.</dd>
            </dl>
        </div>
        <div>
            <h3 id="debug">Debug</h3>
            <dl>
                <dt><samp>JPDA_ADDRESS</samp></dt>
                <dd>The address through which Java debugger can connect, for example <samp>*:8000</samp>. Note that the port has to be mapped to host in order for the debugger to work, e.g. <samp>8080:8080</samp>.</dd>
                <dt><samp>CATALINA_OPTS</samp></dt>
                <dd>Tomcat's Java options</dd>
            </dl>
        </div>
        <div>
            <h3 id="proxy">Proxy</h3>
            <dl>
                <dt><samp>LDHC_FRONTEND_PROXY</samp></dt>
                <dd>Frontend proxy URL for HTTP requests (optional)</dd>
                <dd>Configures a proxy server for the HTTP client infrastructure layer when making frontend requests</dd>
                <dt><samp>LDHC_BACKEND_PROXY</samp></dt>
                <dd>Backend proxy URL for SPARQL service access (optional)</dd>
                <dd>Configures a proxy server for accessing SPARQL services and backend endpoints</dd>
            </dl>
        </div>
        <div>
            <h3 id="http-client">HTTP client timeouts</h3>
            <p>Timeouts and connection lifetimes for LinkedDataHub's pooled HTTP clients, used for the <a href="../http-api/#ld-proxy">Linked Data proxy</a> and for accessing SPARQL services. All values are in milliseconds and are passed as <samp>CATALINA_OPTS</samp> system properties.</p>
            <dl>
                <dt><samp>CLIENT_SOCKET_TIMEOUT</samp></dt>
                <dd>Socket (read) timeout — how long to wait for data on an established connection. By default <samp>120000</samp>.</dd>
                <dt><samp>CLIENT_CONNECT_TIMEOUT</samp></dt>
                <dd>Connection timeout — how long to wait to establish a connection. By default <samp>10000</samp>.</dd>
                <dt><samp>CLIENT_CONNECTION_TIME_TO_LIVE</samp></dt>
                <dd>Maximum lifetime of a pooled connection before it is closed. By default <samp>300000</samp>.</dd>
                <dt><samp>CLIENT_VALIDATE_AFTER_INACTIVITY</samp></dt>
                <dd>Idle time after which a pooled connection is validated before reuse. By default <samp>10000</samp>.</dd>
            </dl>
        </div>
        <div>
            <h3 id="varnish">Varnish</h3>
            <dl>
                <dt><samp>VARNISH_FRONTEND_BACKEND_PORT</samp></dt>
                <dd>Port for frontend Varnish backend (default: <samp>7070</samp>)</dd>
                <dd>Can be customized when running LinkedDataHub behind additional proxies or in non-standard Docker networking configurations</dd>
                <dt><samp>VARNISH_ADMIN_BACKEND_PORT</samp></dt>
                <dd>Port for admin Varnish backend (default: <samp>3030</samp>)</dd>
                <dd>Can be customized when running LinkedDataHub behind additional proxies or in non-standard Docker networking configurations</dd>
                <dt><samp>VARNISH_END_USER_BACKEND_PORT</samp></dt>
                <dd>Port for end-user Varnish backend (default: <samp>3030</samp>)</dd>
                <dd>Can be customized when running LinkedDataHub behind additional proxies or in non-standard Docker networking configurations</dd>
            </dl>
        </div>
    </div>
    <div>
        <h2 id="nginx">nginx</h2>
        <dl>
            <dt><samp>SERVER_CERT_FILE</samp></dt>
            <dd>Location of the server's SSL certificate. By default <samp>/etc/nginx/ssl/server.crt</samp>.</dd>
            <dt><samp>SERVER_KEY_FILE</samp></dt>
            <dd>Location of the server's SSL certificate's key. By default <samp>/etc/nginx/ssl/server.key</samp>.</dd>
            <dt><samp>SSL_VERIFY_CLIENT</samp></dt>
            <dd><samp>off</samp> to disable TLS client certificate authentication on the <samp>$HTTPS_PORT</samp> port, which also disables LinkedDataHub's <a href="../../get-started/get-an-account/">WebID-TLS authentication method</a>.</dd>
            <dd>This option can be used to avoid the certificate prompt in the browser in end-user facing applications. The client certificate authentication is still available on port 5443.</dd>
            <dd><samp>optional_no_ca</samp> to enable it.</dd>
            <dt><samp>MAX_BODY_SIZE</samp></dt>
            <dd>Maximum allowed request body size (<samp>linkeddatahub</samp> has a separate setting for this.) By default <samp>2097152</samp>.</dd>
        </dl>
        <p>By default nginx is configured to guard against DoS by limiting the rate of requests per second, which can be necessary on a public instance. The limiting can be disabled in <samp>platform/nginx.conf.template</samp>
            by commenting out all lines starting with <samp>limit_req</samp> using <samp>#</samp>.</p>
        <div>
            <h3 id="server-certs">Server certificates</h3>
            <p>The certificates generated by the <samp>server-cert-gen.sh</samp> script are self-signed and therefore are shown as
            "not secure" in web browsers. On a local machine this shouldn't be a problem; on public/production servers we recommend
            using <a href="https://letsencrypt.org/" target="_blank">LetsEncrypt</a> certificates. They can be mounted into nginx as follows:</p>
            <pre><code>  nginx:
    environment:
      - SERVER_CERT_FILE=/etc/letsencrypt/live/kgdev.net/fullchain.pem
      - SERVER_KEY_FILE=/etc/letsencrypt/live/kgdev.net/privkey.pem
    volumes:
      - /etc/letsencrypt:/etc/letsencrypt</code></pre>
        </div>
        <p><a href="#http"><samp>SELF_SIGNED_CERT</samp></a> should be set to <samp>false</samp> in this case.</p>
    </div>
</div>"""^^rdf:XMLLiteral .