Running Unblu in standalone mode
There are a number of scenarios—testing, development, or demos, for example—where it can be useful to deploy an Unblu server to your local machine. In such cases, you can deploy Unblu in standalone mode.
Standalone mode isn’t suitable for production use. |
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).
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;
cd elastic-start-local
./start.sh
When you’ve finished run the following command to 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:
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:
docker start opensearch
If you encounter any issues, a sensible first step is to run the following command:
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.
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:
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 Dockerjava -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 ofES_LOCAL_PASSWORD
from the.env
file inelastic-start-local/
.2 Replace <version>
and<guid>
with the correct values. -
For OpenSearch, it looks like this:
Listing 10. Start Unblu with OpenSearch in Dockerjava -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:
-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
:
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.
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
:
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
.