Running Unblu in standalone mode

Requirements

Any reasonably modern machine should be capable of running Unblu in standalone mode. For example, a machine with the following specifications will do the job:

1 recent CPU core running at 2.4GHz
4 GB RAM
10 GB hard drive space

You will also need:

Java 21 installed on the computer where you want to run Unblu
The Unblu installation package, consisting of the following elements:
- The Unblu WAR file
- A valid Unblu license key
An Unblu properties file (optional)
A search engine

Search engine

Starting with Unblu 8.22.1, Unblu requires access to a search engine. Unblu supports Elasticsearch and OpenSearch.

One way to provision a search engine for development purposes is to use Docker.

Elasticsearch

To run a local development instance of Elasticsearch in Docker, open a terminal and run the command below. Note that on Windows, this requires the Windows Subsystem for Linux (WSL).

Listing 1. Provision Elasticsearch in Docker for Unblu full-text search

curl -fsSL https://elastic.co/start-local | sh -s -- --esonly -v <elasticsearch-version> (1)

1	Replace `<elasticsearch-version>` with a version of Elasticsearch supported by Unblu.

This creates a folder called elastic-start-local with all the files needed to run Elasticsearch locally. To launch Elasticsearch, run the following commands;

Listing 2. Launch Elasticsearch locally in Docker

cd elastic-start-local
./start.sh

When you’ve finished run the following command to stop Elasticsearch:

Listing 3. Stop Elasticsearch

./stop.sh

For more detailed information about running Elasticsearch in Docker, refer to the article Local development installation (quickstart) in the Elasticsearch documentation and the README of the start-local script.

OpenSearch

To run OpenSearch in Docker, run the following commands in your terminal:

Listing 4. Provisioning OpenSearch in Docker for Unblu full-text search

docker run -d -p 9200:9200 -p 9600:9600 \
  -e "discovery.type=single-node" \
  -e "OPENSEARCH_INITIAL_ADMIN_PASSWORD=<opensearch-admin-password>" \ (1)
  --name "opensearch" opensearchproject/opensearch:<opensearch-version> (2)

docker cp opensearch:/usr/share/opensearch/config/root-ca.pem .

keytool -importcert -file root-ca.pem -keystore root-ca.jks -alias root-ca -storepass <trusted-store-password> (3)

1	Replace `<opensearch-admin-password>` with a password of your choice.
2	Replace `<opensearch-version>` with a version of OpenSearch supported by Unblu.
3	Replace `<trusted-store-password>` with a password of your choice.

Once you’ve run the commands above once, you can launch OpenSearch in Docker with the following command:

Listing 5. Launch OpenSearch in Docker

docker start opensearch

If you encounter any issues, a sensible first step is to run the following command:

Listing 6. Launch OpenSearch in Docker

docker opensearch log

For more detailed information about running OpenSearch in Docker, refer to the Docker article in the OpenSearch documentation.

Deployment

As an Unblu customer, you’re typically granted access to a downloadable file with a name like product.com.unblu-<version>-<guid>.war. The Unblu WAR file can also be used as an executable JAR. In standalone mode, it runs using an embedded Jetty-based web server.

Listing 7. Starting Unblu with default configuration

java -jar product.com.unblu-<version>-<guid>.war (1)

1	Replace `<version>` and `<guid>` with the correct values.

The embedded Jetty web server automatically selects a TCP port in the range of 6060—7070. To specify the TCP port yourself, add -Dport= on the command line:

Listing 8. Starting Unblu with a specific TCP port

java -Dport=6789 \
     -jar product.com.unblu-<version>-<guid>.war

If you’re running the search engine in Docker as described above and you didn’t add the search engine configuration properties to your properties file, you must provide them as command-line arguments:

For Elasticsearch, the command looks like this:

Listing 9. Start Unblu with Elasticsearch in Docker

java -Dcom.unblu.search.engine.type=ELASTIC_SEARCH \
  -Dcom.unblu.search.engine.es.host=http://localhost:9200 \
  -Dcom.unblu.search.engine.es.authType=BASIC \
  -Dcom.unblu.search.engine.es.username=elastic \
  -Dcom.unblu.search.engine.es.password=<search-engine-password> \ (1)
 -jar product.com.unblu-<version>-<guid>.war (2)

1	Replace `<search-engine-password>` with the value of `ES_LOCAL_PASSWORD` from the `.env` file in `elastic-start-local/`.
2	Replace `<version>` and `<guid>` with the correct values.

For OpenSearch, it looks like this:

Listing 10. Start Unblu with OpenSearch in Docker

java -Dcom.unblu.search.engine.type=OPEN_SEARCH \
  -Dcom.unblu.search.engine.os.host=https://localhost:9200 \
  -Dcom.unblu.search.engine.os.authType=BASIC \
  -Dcom.unblu.search.engine.os.username=admin \
  -Dcom.unblu.search.engine.os.password=<opensearch-admin-password> \ (1)
  -Dcom.unblu.search.engine.os.pathToTrustedCertsKeyStoreFile=./root-ca.jks \
  -Dcom.unblu.search.engine.os.trustedCertsKeyStorePassword=<trusted-store-password> \ (2)
  -jar product.com.unblu-<version>-<guid>.war (3)

1	Replace `<opensearch-admin-password>` with the password you defined for the search engine.
2	Replace `<trusted-store-password>` with the password defined for the key store.
3	Replace `<version>` and `<guid>` with the correct values.

Command line options

The following command line options are available when you run the executable JAR file:

Listing 11. Options and description

-e,--export <arg>   Type of export. Possible options: 'ear' or 'wjar'
-h,--help	          Display this help message
-l,--list           Format of output: ( version: build: branch: )
-m,--migrationOnly  use to shutdown the product after database migration is complete
-o,--output <arg>   File to write the exported product to. If not given, output will default to STDOUT.
-p,--product <arg>  ID of the product to start, for example product.com.unblu.enterprise (default) (1)
-t,--test           Include test bundles into the product execution/export (not available in production versions).
-d,--diag           Include diagnostics bundles in the product execution/export (not available in production versions).

1	The `--product` switch is also available via System Properties.

These options are placed after -jar product.com.unblu-<version>-<guid>.war:

Listing 12. Placement of command line options when launching Unblu in standalone mode

java
     -jar product.com.unblu-<version>-<guid>.war \ (1)
     --help

1	Replace `<version>` and `<guid>` with the correct values.

Configuration

All configuration can be placed in a separate properties file.

Listing 13. Example properties file

com.unblu.runtime.jetty.port=7777

# Create a superadmin on DB setup
com.unblu.storage.createSuperAdmin=true
com.unblu.storage.superAdminUsername=
com.unblu.storage.superAdminPassword=superadmin

If you don’t specify the property com.unblu.storage.superAdminUsername, Unblu generates a random superadmin username.

To use your properties file, include its name in the command line argument -Dcom.unblu.propertyoverlay:

Listing 14. Start Unblu using the properties file unblu-config.properties

java -Dcom.unblu.propertyoverlay=unblu-config.properties \
    -Dport=7070 \
    -jar product.com.unblu-<version>-<guid>.war (1)

1	Replace `<version>` and `<guid>` with the correct values.

If you need to use the Unblu JavaScript demo page, activate it by setting com.unblu.server.resources.enableDemoResources to true. If you also want the Unblu documentation available locally, set com.unblu.server.resources.enableDocResources to true.

Log output

In standalone mode, Unblu writes log entries to standard output. Alternatively, Unblu can write two log files.

Log file configuration

The two log files are:

Main log file: The main log file is a general-purpose log file. All status messages, errors, warnings, and debug messages are written to the main log file. The default name of the main log file is unblu.<date>.log.
Fatal log file: The fatal log file is an extract of the general-purpose log file. It only contains fatal errors. The default name of the fatal log file is unblu-fatal.<date>.log.

The logging system can be configured with the following configuration properties:

com.unblu.logging.outputDirectory specifies the file system directory that log files are written to. If no output directory is configured, Unblu writes log entries to standard output.
com.unblu.logging.fileNameFormat defines the format of the log filenames.
com.unblu.logging.fatalLogEnabled enables the fatal log file. Set it to false to disable.
com.unblu.logging.mainLogFormat and com.unblu.logging.fatalLogFormat define the format of the main and fatal log files. The fatal log format defaults to the main log format. The default format is described in Log file format.
com.unblu.logging.mainLogMaxHistory and com.unblu.logging.fatalLogMaxHistory specify how many days the main and fatal log files are retained.

Log file format

The main and fatal log files have the following format:

Listing 15. Default log file format

# Format
DATE [THREAD] [CONTEXT_INFO] LEVEL  LOGGER - MESSAGE
# Example output
2026-05-04T13:30:01.346Z [                main] [u: s: c: p: r: e: traceId: spanId: correlationId: ] INFO  com.unblu.platform.server.core.RuntimeProductResolver - Hello

Each element of the format corresponds to a part of the example output:

DATE: ISO 8601 timestamp in UTC.
THREAD: The name of the thread that emitted the log entry, padded to 20 characters (main in the example).
CONTEXT_INFO: Diagnostic context for the log entry, formatted as space-separated <key>: <value> pairs.
LEVEL: The log level (INFO, WARN, and so on), padded to 5 characters.
LOGGER: The fully qualified name of the logger.
MESSAGE: The log message.

The keys in the CONTEXT_INFO block are:

u: <userId>: User
s: <sessionId>: Web session, identified by the x-unblu-session cookie
c: <clientId>: Client
p: <pageId>: Page impression in a browser client
r: <requestId>: HTTP request
e: <executionId>: Execution
traceId: <traceId>: Distributed trace ID
spanId: <spanId>: Distributed span ID
correlationId: <correlationId>: Correlation ID
<customTraceHeaders>: Custom trace headers (no prefix; raw value)

All information in the CONTEXT_INFO section is optional. It’s only available if the log output was generated in a context associated with the information in question.

Console log format

In standalone mode, log entries written to standard output have the following format:

Listing 16. Default console log format

# Format
DATE [PREFIX][THREAD] [CONTEXT_INFO] LEVEL  (LOGGER) MESSAGE
# Example output
2026-05-04T13:30:01.346Z  [                main] [u: s: c: p: r: e: traceId: spanId: correlationId: ] INFO  (c.u.p.s.c.RuntimeProductResolver) Hello

The DATE, THREAD, CONTEXT_INFO, LEVEL, and MESSAGE fields work the same way as in Log file format. The PREFIX and LOGGER fields differ:

PREFIX: Optional prefix taken from the X-Prefix MDC key. Defaults to a single space when no prefix is set.
LOGGER: The logger name, abbreviated. Package segments are reduced to single characters; the class name is kept in full.

To customize the format, set com.unblu.logging.consoleLogFormat to a Logback pattern of your choice.

Log file rotation

All log files are rotated on a daily basis. This means that in the logging output directory for every log type (main, fatal) you will get a file for each day.

By default, Unblu cleans out old log files for the main and the fatal log files after seven days.