# System properties

## Overview

Joule internal setting can be custom configured to **suit the needs of your environment**.

This guide allows precise control over Joule’s setup for optimised deployment.

Key sections include:

1. <mark style="color:green;">**General configuration**</mark>\
   Set metadata and enable core services like the internal database and REST API.
2. <mark style="color:green;">**Service enabling**</mark>\
   Control features such as event lineage, internal database, and REST API.
3. <mark style="color:green;">**Database settings**</mark>\
   Configure Joule’s embedded DuckDB for metrics and state queries, including memory limits and thread usage.
4. <mark style="color:green;">**Rest API**</mark>\
   Customise REST API options, including file handling, security, and SSL settings.

## Example configuration

```properties
# General Rest API details 
joule.version=1.1.0
joule.contact.name=Lyndon Adams
joule.contact.email=enquiries@fractalworks.io
joule.contact.url=https://fractalworks.io

# Enable service switches
joule.lineage.enable=false
joule.internaldb.enable=true
joule.restapi.enable=true

# Internal database setting
joule.db.path=./db/joule.db
joule.db.memoryOnly=false
joule.db.memory_limit='512MB'
joule.db.access_mode=READ_WRITE
joule.db.threads=2
joule.db.worker_threads=2
joule.db.default_order='DESC'

# RestAPI setting
joule.rest.port=9080

# Directory to write files that exceed the in-memory limit
joule.rest.downloadPath=downloads

# The maximum individual file size allowed In GB
joule.rest.maxFileSize=2

# The maximum file size to handle in memory in MB
joule.rest.InMemoryFileSize=100

# The maximum size of the entire multipart request in GB
joule.rest.totalRequestSize=5

# SSL config
joule.rest.enableSSL=false
joule.rest.pemCertPath=./conf/cert.pem
joule.rest.keyCertPath=./conf/key.pem
```

### Joule CLI switch

Apply the below command line switch to the Joule process when using a custom `joule.properties` file. Setting within this file will override the default setting.

{% hint style="info" %}
To override the default setting provide a single configuration file and use the `-c` command line switch to specify the file path.
{% endhint %}

```
-c /app/joule/config/joule.properties
```

### Enable services

To enable services using default setting the following&#x20;

```properties
# Enable service switches
joule.lineage.enable=false
joule.internaldb.enable=true
joule.restapi.enable=true
```

### Event lineage&#x20;

Any event processor that changes the state of the passed event can have this action recorded within the event. There is a small memory overhead to keep changed state. &#x20;

```properties
joule.lineage.enable=false
```

This is currently an experimental feature which is undergoing further development to determine its usefulness within a stream processing context. Therefore it is set to disabled as a default setting.

### Internal database

Joule ships with an embedded database, [DuckDB](https://duckdb.org/), that provides core features such as metrics processing, event tapping and external state queries. This feature is enabled by default.

```properties
joule.internaldb.enable=true
```

See [internal database configuration](#internal-database-configuration) for further details.

### Rest API

Joule ships with an embedded Rest API that provides external query and Web socket APIs. See [Rest API](#rest-api-configuration) documentation for further details. This feature is enabled by default.

```properties
joule.restapi.enable=true
```

See [Rest API configuration](#rest-api-configuration) for further details.

## Internal database configuration

Joule ships with an in-memory database to support event capturing, metrics and ad-hoc queries for processors.&#x20;

### Example

```yaml
# Internal database setting
joule.db.path=./db/joule.db
joule.db.memoryOnly=false
joule.db.memory_limit=4GB
joule.db.access_mode=READ_WRITE
joule.db.threads=8
joule.db.default_order=DESC
```

### Attributes schema

<table><thead><tr><th>Property</th><th width="307">Description</th><th>Default</th></tr></thead><tbody><tr><td>joule.db.path</td><td>Relative path to the Joule process include database file name.</td><td><em>default: ./db/joule.db</em></td></tr><tr><td>joule.db.memoryOnly</td><td>Boolean flag set to true an <strong>in-memory database</strong> is created. Note that for an in-memory database no data is persisted to disk. </td><td><em>default: false</em></td></tr><tr><td>joule.db.memory_limit</td><td>The maximum memory of the database system (e.g. 1GB)</td><td><em>default: 512MB</em></td></tr><tr><td>joule.db.access_mode</td><td>Access mode of the database (<strong>AUTOMATIC</strong>, <strong>READ_ONLY</strong> or <strong>READ_WRITE</strong>).</td><td><em>default: READ_WRITE</em></td></tr><tr><td>joule.db.threads</td><td>The number of total worker threads used by the database.</td><td><em>default: 2</em></td></tr><tr><td>joule.db.default_order</td><td>The query set order type used when none is specified (<strong>ASC</strong> or <strong>DESC</strong>).</td><td><em>default: DESC</em></td></tr></tbody></table>

### Rest API Configuration&#x20;

Joule enables Rest API when the in-memory database is enabled. Dynamic endpoints are created to support data exports and paginated queries. See [Rest API documentation](/joule/components/connectors/sources/rest-endpoints.md) for further information.

```properties
# RestAPI setting
joule.rest.port=9080

# Directory to write files that exceed the in-memory limit
joule.rest.downloadPath=downloads

# The maximum individual file size allowed In GB
joule.rest.maxFileSize=2

# The maximum file size to handle in memory in MB
joule.rest.InMemoryFileSize=100

# The maximum size of the entire multipart request in GB
joule.rest.totalRequestSize=5

# SSL config
joule.rest.enableSSL=false
joule.rest.pemCertPath=./conf/cert.pem
joule.rest.keyCertPath=./conf/key.pem
```

### Attributes schema

<table><thead><tr><th width="251">Property</th><th width="295">Description</th><th>Default</th></tr></thead><tbody><tr><td>joule.rest.port</td><td>Rest API port</td><td><em>default: 9080</em></td></tr><tr><td>joule.rest.downloadPath</td><td>Directory the system rest consumer will download files to ready for data ingestion<br>See <a href="/pages/ydyxcKmpbswnrAiFjhL2">Rest API</a> documentation</td><td><em>default: downloads</em></td></tr><tr><td>joule.rest.maxFileSize</td><td>The maximum individual file size allowed In GB</td><td><em>default: 2GB</em></td></tr><tr><td>joule.rest.InMemoryFileSize</td><td>The maximum file size to handle in memory in MB</td><td><em>default: 100MB</em></td></tr><tr><td>joule.rest.totalRequestSize</td><td>The maximum size of the entire multipart request in GB</td><td><em>default: 5GB</em></td></tr><tr><td>joule.rest.enableSSL</td><td><p>If you want to secure your Joule process with SSL set this flag to true.</p><p>Supported certificate formats are PKCS#12 (.p12) and PKCS#8 (.pem) and Java KeyStore (.jks).</p></td><td><em>default: false</em></td></tr><tr><td>joule.rest.pemCertPath</td><td>Certificate from a trusted CA or a self-signed certificate.</td><td><p><em>default:</em></p><p><em>/app/joule/certs/cert.pem</em></p></td></tr><tr><td>joule.rest.keyCertPath</td><td>Private key</td><td><p><em>default:</em></p><p><em>/app/joule/certs/key.pem</em></p></td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fractalworks.io/joule/developer-guides/system-configuration/system-properties.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.