Installing on Docker

Get started quickly by deploying Nuix RESTful Service on Docker

8 minute read

Follow the procedures in this section to install and deploy the Nuix RESTful Service Docker image within a Ubuntu Linux environment using Compose.

The Nuix RESTful Service Docker image is intended for development purposes only. Usage of this installation in a production environment is not supported.

Prerequisites

Before proceeding, the following prerequisites must be installed within your environment:

Docker Engine: An open-source containerization technology.
- Visit Get Docker Engine - Community for Ubuntu for complete instructions on installing the Docker Engine on Ubuntu.
  Note:To ensure proper operation, the Docker Engine requires a minimum of 8 GB of memory.
Docker Compose: A tool used to define and run multi-container Docker applications.
- Visit Install Docker Compose for complete instructions on installing Docker Compose.
  Note:The Docker Engine must be installed and running before installing Docker Compose. View the Post-installation steps for Linux for details on configuring different startup methods for Docker.

Preparing the Target Directory

Use the following procedure to download and extract the Nuix RESTful Service Linux archive.

Download the Docker Image for Linux 64-bit package from the Nuix Customer Portal.
Open a terminal and enter the following command to create a target directory for the package:
```
sudo mkdir -p /opt/nuix/rest
```
Note: /opt/nuix/rest is the recommended location for this package.
Extract the contents of the rest-docker-compose archive to the target directory:
```
sudo tar xzf rest-docker-compose-VERSION.tar.gz -C /opt/nuix/rest
```
Navigate to the target directory to view the extracted contents of the package:
```
cd /opt/nuix/rest
```

The rest directory contains the directory structure described in the following table:

    .
    |-- bin                                       # Binaries and support scripts
        |-- clean.sh                              # Script to remove user data and restore directories
        |-- configure.sh                          # Script to configure the Nuix License Server settings
        |-- create-service.sh                     # Script to create a service
        |-- install.sh                            # Script to install the Nuix RESTful Service
    |-- cases                                     # Default Inventory Location for cases on the host
    |-- docs                                      # Documentation
    |-- exports                                   # Default Nuix exports directory on the host
    |-- images                                    # Distributed Docker images
    |-- logs                                      # Default Nuix logs directory on the host
    |-- raw-data                                  # Default Nuix raw-data directory on the host
    |-- scripts                                   # Default Nuix scripts directory on the host
    |-- secrets                                   # Sensitive properties used by the Nuix Rest SDK
        |-- nuix-rest-secret.properties           # Sensitive Nuix License Server properties
    |-- tmp                                       # Default Nuix tmp directory on the host
    |-- user-data-extra                           # Default Nuix user-data-extra folder on the host
    |-- .env                                      # Docker compose environment configuration.
    |-- rest.env                                  # Nuix RESTful Service environment configuration
    |-- docker-compose.yml                        # Docker compose file

Installing the Docker Image

After extracting the package to the target directory, use the following procedure to complete the installation process using the provided scripts.

Open a terminal and navigate to the target directory.
```
cd /opt/nuix/rest
```
Enter the following command to begin the installation.
```
sudo ./bin/install.sh
```
The install.sh script verifies that all prerequisites are in place before loading the included Nuix RESTful service Docker images and calling all other scripts that are required for the installation.
Note: The first time install.sh is run, a warning is returned indicating that rest.env is missing and will be created from an example file that contains default values. This is expected and can be ignored. See Post-Installation Configuration after completing the installation for information on modifying the default environment configurations.
When prompted, specify the Nuix License Server that will be used for licensing.
1. Enter a URL where the license server can be accessed.
2. Provide user credentials for an account associated within the specified license server.

After installation completes, proceed to the remaining sections in this guide for information on:

Configuring environment settings
Updating Nuix License Server settings
Removing user data form an existing installation
Starting Nuix RESTful Service
Verifying your installation

Post-Installation Configuration

After completing the installation of Nuix RESTful Service, the following configurations can be made to the installation.

Configuring Environment Settings

Nuix RESTful Service includes several configurations that can be modified to change the how the application operates.

Use the following procedure to access the available environment configurations:

Open a terminal and navigate to the target directory.
```
cd /opt/nuix/rest
```
Using the editor of your choice, open the following configuration file.
```
rest.env
```
Review the properties included within the file and make changes as necessary.

The following table provides details about the properties that are configurable.

Option	Description
`JAVA_OPTS_HEAP`	Optimize the Java heap size ranges used by Nuix RESTful service. * -Xms512m Default minimum memory allocation * -Xmx6g Default maximum memory allocation
`publicURL`	The URL used to access Nuix RESTful Service.
`logging_level`	Specify the logging level to be used with REST.
`logging_level_com_nuix_us`	Specify the logging level to be used for workers.
`casePrivilegeSecurityEnabled`	Enable or disable the ability to restrict cases from view using case security.
`threadpool_nativesearch`	The number of threads available for retrieving item metadata when searches are performed.
`threadpool_asyncfunction`	The number of threads available to perform background tasks such as tagging, exclusions, or highlighting.
`threadpool_searchUnsortedManager`	The number of threads available for retrieving item counts for the provided analytics.
`threadpool_searchUnsorted`	The number of threads available to run queries and aggregate the data required to populate the provided analytics.
`serverId`	A unique identifiable name for the REST instance.
`xpack_security_transport_ssl_enabled`	Enable or disable TLS/SSL.
`ignoreDerbyCases`	Restrict REST from processing Derby-based cases.
`nuix_engine_userDataDirs`	Specify the locations where artifacts used by the Nuix Engine are stored.
`inventoryLocations`	Specify the location where cases are stored. Mapped network drives can be configured within Linux environments if a symbolic link has been created between the mapped and local drive.
`sandboxDirectory`	Specify a location where unprocessed evidence is stored.
`server_contextPath`	Specify a context path prefix to use within the Nuix RESTful Service URL.
`workerAgentStatusHistoryUpdateIntervalMs`	Specify the frequency (in milliseconds) in which worker agent status is retrieved.
`workerAgentStatusHistoryMaxValues`	Specify the maximum number of times that worker agent status can be retrieved.
`registerAsApplication`	Specify how Nuix RESTful Service should be run.
`maxSimultaneousWorkers`	Specify the total number of workers that can be distributed by this REST instance at any given time.
`workerAgentTempPath`	Specify the path to a directory, such as /tmp, that can be used by worker agents for temporary storage. The specified location should be on performant local storage with ample space for best results.
`nuix_logdir`	Specify the directory where logs generated by Nuix RESTful Service are stored.
`nuix_engine_path`	Specify the directory where the Nuix Engine is installed.
`logging_file`	Specify the path and file name to use for the log file.
`logging_config`	Specify the path and file name of the logging configuration file.

When finished, save and exit the file, then restart Nuix RESTful Service for the changes to take effect.

Updating Nuix License Server Settings

If required, the configured Nuix License Server can be updated after the initial installation using a provided script.

Use the following procedure to update the Nuix License Server connection details:

Open a terminal and navigate to the target directory.
```
cd /opt/nuix/rest
```
Enter the following command to run the script and update the connection details.
```
sudo ./bin/configure.sh
```
When prompted, specify the Nuix License Server to be used for licensing.
1. Enter a URL where the license server can be accessed.
2. Provide user credentials for an account associated within the specified license server.

The updated settings are saved to the ./secrets/nuix-rest-secret.properties file as well as the ./rest.env file.

Once complete, restart Nuix RESTful Service for the changes to take effect.

Removing Existing Data

Nuix RESTful Service provides a script that allows all case, evidence, and user data to be removed without impacting the installation. This script can be used to return the Docker image back to a default state when testing different scenarios.

To remove existing data from the installation:

Warning

All existing cases, engine artifacts, and raw evidence will be deleted.

Open a terminal and navigate to the target directory.
```
cd /opt/nuix/rest
```
Enter the following command to run the script.
```
sudo ./bin/clean.sh
```

Running Nuix RESTful Service

Once the Docker image has been properly deployed and configured on your system, Docker Compose can be used to quickly start Nuix RESTful Service.

To start the service in the foreground:

Navigate to the target directory where Nuix RESTful Service is installed:
```
cd /opt/nuix/rest
```
Start the service using the following command:
```
sudo docker-compose up
```
Note:This startup method returns all logs within the terminal which may be helpful when troubleshooting an issue. While the service is running, the terminal cannot be used.
To stop the service, press Ctrl-C within the terminal.

To start the service in the background:

Navigate to the target directory where Nuix RESTful Service is installed:
```
cd /opt/nuix/rest
```
Start the service using the following command:
```
sudo docker-compose up -d
```
Note: This startup method does not return logs but allows continued use of the terminal.
To stop the service, enter the following command:
```
sudo docker-compose stop
```

Starting as a Service

The installation script provided with Nuix RESTful Service creates all required Docker entries to allow the image to be run as a service. By default, the services are not started or configured to start on boot, however, these configurations can be changed using the following commands.

Start as a service:

sudo systemctl start docker-compose@nuix-rest-sdk

Stop the service from running:

sudo systemctl stop docker-compose@nuix-rest-sdk

Configure Nuix RESTful Service to run at startup:

sudo systemctl enable docker-compose@nuix-rest-sdk

Verifying the Installation

Once your installation is complete, verify your deployment using one of the following methods.

From a web browser, access the following URL:

localhost:8080/nuix-restful-service/svc/v2/about

From the terminal, enter the following cURL:

curl http://localhost:8080/nuix-restful-service/svc/v2/about

If the installation was successful, the response body for either method will return with information about the RESTful service.

{
 "server" : "http://localhost:8080/nuix-restful-service/svc",
 "serverId" : "rest-server",
 "startupTime" : null,
 "nuixRestfulVersion" : null,
 "engineVersion" : null
}

Feedback

Was this page helpful?

Thank you for your feedback.