1. Quick Start Tutorial

This quick tutorial enables installation, configuration, and usage of a basic instance of Alliance.

Note

This tutorial is intended for setting up a test, demonstration, or trial installation of Alliance. For complete installation and configuration steps, see Installing.

These steps demonstrate:

1.1. Installing (Quick Start)

These are the basic requirements to set up the environment to run a Alliance.

Warning

For security reasons, Alliance cannot be started from a user’s home directory. If attempted, the system automatically shuts down.

1.1.1. Quick Install Prerequisites

Hardware Requirements (Quick Install)

  • At least 4096 MB of memory for Alliance.

Java Requirements (Quick Install)

Follow the instructions outlined in Java Requirements.

Warning
Check System Time

Prior to installing Alliance, ensure the system time is accurate to prevent federation issues.

1.1.2. Quick Install of SolrCloud

  1. Download a preconfigured Solr distribution zip file This link is outside the Alliance documentation.

  2. Unzip the Solr zip file.

  3. Run <solr_directory>/bin/solr -e cloud.

    1. Press enter to default to 2 nodes.

    2. Enter 8994 for node 1 port.

    3. Enter 8995 for node 2 port.

    4. Press enter for all other prompts to accept defaults.

1.1.3. Quick Install of Alliance

Warning
 The Alliance installation cannot succeed unless SolrCloud is running. See Quick Install of SolrCloud for instructions.

  1. Download the Alliance zip file This link is outside the Alliance documentation.

  2. Install Alliance by unzipping the zip file.

    Warning
    Windows Zip Utility Warning

    The Windows Zip implementation, which is invoked when a user double-clicks on a zip file in the Windows Explorer, creates a corrupted installation. This is a consequence of its inability to process long file paths. Instead, use the java jar command line utility to unzip the distribution (see example below) or use a third party utility such as 7-Zip.

    Note
    		 If and only if a JDK is installed, the jar command may be used; otherwise, another archiving utility that does not have issue with long paths should be installed
    Use Java to Unzip in Windows(Replace <PATH_TO_JAVA> with correct path and <JAVA_VERSION> with current version.)
    "<PATH_TO_JAVA>\jdk<JAVA_VERSION>\bin\jar.exe" xf alliance-1.17.6.zip

  3. This creates an installation directory, which is typically created with the name and version of the application. This installation directory is referred to as <ALLIANCE_HOME>. (Substitute the actual directory name.)

  4. Edit <ALLIANCE_HOME>/etc/custom.system.properties and update solr.cloud.zookeeper=localhost:2181 to solr.cloud.zookeeper=localhost:9994

  5. Start Alliance by running the <ALLIANCE_HOME>/bin/alliance script (or alliance.bat on Windows).

  6. Startup may take a few minutes.

    1. Optionally, a system:wait-for-ready command (aliased to wfr) can be used to wait for startup to complete.

  7. The Command Console displays.

Command Console Prompt
alliance@local>

1.1.4. Quick Install of Alliance on a remote headless server

If Alliance is being installed on a remote server that has no user interface, the hostname must be updated in the configuration files and certificates.

Note

Do not replace all instances of localhost, only those specified.
Configuring with a new hostname

  1. Update the <ALLIANCE_HOME>/etc/custom.system.properties file. The entry org.codice.ddf.system.hostname=localhost should be updated to org.codice.ddf.system.hostname=<HOSTNAME>.

  2. Update the <ALLIANCE_HOME>/etc/users.properties file. Change the localhost=localhost[…​] entry to <HOSTNAME>=<HOSTNAME>. (Keep the rest of the line as is.)

  3. Update the <ALLIANCE_HOME>/etc/users.attributes file. Change the "localhost" entry to "<HOSTNAME>".

  4. From the console go to <ALLIANCE_HOME>/etc/certs and run the appropriate script.

    1. *NIX: sh CertNew.sh -cn <hostname> -san "DNS:<hostname>".

    2. Windows: CertNew -cn <hostname> -san "DNS:<hostname>".

  5. Proceed with starting the system and continue as usual.

Configuring with an IP address

  1. Update the <ALLIANCE_HOME>/etc/custom.system.properties file. The entry org.codice.ddf.system.hostname=localhost should be updated to org.codice.ddf.system.hostname=<IP>.

  2. Update the <ALLIANCE_HOME>/etc/users.properties file. Change the localhost=localhost[…​] entry to <IP>=<IP>. (Keep the rest of the line as is.)

  3. Update the <ALLIANCE_HOME>/etc/users.attributes file. Change the "localhost" entry to "<IP>".

  4. From the console go to <ALLIANCE_HOME>/etc/certs and run the appropriate script.

    1. *NIX: sh CertNew.sh -cn <IP> -san "IP:<IP>".

    2. Windows: CertNew -cn <IP> -san "IP:<IP>".

  5. Proceed with starting the system and continue as usual.

Note
File Descriptor Limit on Linux

  • For Linux systems, increase the file descriptor limit by editing /etc/sysctl.conf to include:

fs.file-max = 6815744

  • (This file may need permissions changed to allow write access).

  • For the change to take effect, a restart is required.

    1. *nix Restart Command

init 6

1.2. Certificates (Quick Start)

Alliance comes with a default keystore that contains certificates. This allows the distribution to be unzipped and run immediately. If these certificates are sufficient for testing purposes, proceed to Configuring (Quick Start).

To test federation using 2-way TLS, the default keystore certificates needs to be replaced, using either the included Demo Certificate Authority or by Creating Self-signed Certificates.

If the installer was used to install the Alliance and a hostname other than "localhost" was given, the user is prompted to upload new trust/key stores.

If the hostname is localhost or, if the hostname was changed after installation, the default certificates do not allow access to the Alliance instance from another machine over HTTPS (now the default for many services). The Demo Certificate Authority must be replaced with certificates that use the fully-qualified hostname of the server running the Alliance instance.

1.2.1. Demo Certificate Authority (CA)

Alliance comes with a populated truststore containing entries for many public certificate authorities, such as Go Daddy and Verisign. It also includes an entry for the DDF Demo Root CA. This entry is a self-signed certificate used for testing. It enables Alliance to run immediately after unzipping the distribution. The keys and certificates for the DDF Demo Root CA are included as part of the Alliance distribution. This entry must be removed from the truststore before Alliance can operate securely.

1.2.1.1. Creating New Server Keystore Entry with the CertNew Scripts

To create a private key and certificate signed by the Demo Certificate Authority, use the provided scripts. To use the scripts, run them out of the <ALLIANCE_HOME>/etc/certs directory.

*NIX Demo CA Script

For *NIX, use the CertNew.sh script.

sh CertNew.sh [-cn <cn>|-dn <dn>] [-san <tag:name,tag:name,…​>]

where:

  • <cn> represents a fully qualified common name (such as "<FQDN>", where <FQDN> could be something like cluster.yoyo.com)

  • <dn> represents a distinguished name as a comma-delimited string (such as "c=US, st=California, o=Yoyodyne, l=San Narciso, cn=<FQDN>")

  • <tag:name,tag:name,…​> represents optional subject alternative names to be added to the generated certificate (such as "DNS:<FQDN>,DNS:node1.<FQDN>,DNS:node2.<FQDN>"). The format for subject alternative names is similar to the OpenSSL X509 configuration format. Supported tags are:

    • email - email subject

    • URI - uniformed resource identifier

    • RID - registered id

    • DNS - hostname

    • IP - ip address (V4 or V6)

    • dirName - directory name

If no arguments specified on the command line, hostname -f is used as the common-name for the certificate.

Windows Demo CA Script

For Windows, use the CertNew.cmd script.

CertNew (-cn <cn>|-dn <dn>) [-san "<tag:name,tag:name,…​>"]

where:

  • <cn> represents a fully qualified common name (such as "<FQDN>", where <FQDN> could be something like cluster.yoyo.com)

  • <dn> represents a distinguished name as a comma-delimited string (such as "c=US, st=California, o=Yoyodyne, l=San Narciso, cn=<FQDN>")

  • <tag:name,tag:name,…​> represents optional subject alternative names to be added to the generated certificate (such as "DNS:<FQDN>,DNS:node1.<FQDN>,DNS:node2.<FQDN>"). The format for subject alternative names is similar to the OpenSSL X509 configuration format. Supported tags are:

    • email - email subject

    • URI - uniformed resource identifier

    • RID - registered id

    • DNS - hostname

    • IP - ip address (V4 or V6)

    • dirName - directory name

The CertNew scripts:

  • Create a new entry in the server keystore.

  • Use the hostname as the fully qualified domain name (FQDN) when creating the certificate.

  • Adds the specified subject alternative names if any.

  • Use the Demo Certificate Authority to sign the certificate so that it is trusted by the default configuration.

To install a certificate signed by a different Certificate Authority, see Managing Keystores.

After this proceed to Updating Settings After Changing Certificates.

Warning

If the server’s fully qualified domain name is not recognized, the name may need to be added to the network’s DNS server.
1.2.1.2. Dealing with Lack of DNS

In some cases DNS may not be available, and the system needs to be configured to work with IP addresses.

Options can be given to the CertNew Scripts to generate certs that work in this scenario.

*NIX

From <ALLIANCE_HOME>/etc/certs/ run:

sh CertNew.sh -cn <IP> -san "IP:<IP>"

Windows

From <ALLIANCE_HOME>/etc/certs/ run:

CertNew -cn <IP> -san "IP:<IP>"

After this proceed to Updating Settings After Changing Certificates, and be sure to use the IP address instead of the FQDN.

1.2.2. Creating Self-Signed Certificates

If using the Demo CA is not desired, Alliance supports creating self-signed certificates with a self-signed certificate authority. This is considered an advanced configuration.

Creating self-signed certificates involves creating and configuring the files that contain the certificates. In Alliance, these files are generally Java Keystores (jks) and Certificate Revocation Lists (crl). This includes commands and tools that can be used to perform these operations.

For this example, the following tools are used:

1.2.2.1. Creating a custom CA Key and Certificate

The following steps demonstrate creating a root CA to sign certificates.

  1. Create a key pair.
    $> openssl genrsa -aes128 -out root-ca.key 1024

  2. Use the key to sign the CA certificate.
    $> openssl req -new -x509 -days 3650 -key root-ca.key -out root-ca.crt

1.2.2.2. Sign Certificates Using the custom CA

The following steps demonstrate signing a certificate for the tokenissuer user by a CA.

  1. Generate a private key and a Certificate Signing Request (CSR).
    $> openssl req -newkey rsa:1024 -keyout tokenissuer.key -out tokenissuer.req

  2. Sign the certificate by the CA.
    $> openssl ca -out tokenissuer.crt -infiles tokenissuer.req

These certificates are used during system configuration to replace the default certificates.

1.2.3. Updating Settings After Changing Certificates

After changing the certificates, it is necessary to update the system user and the org.codice.ddf.system.hostname property with the value of either the FQDN or the IP.

FQDNs should be used wherever possible. In the absence of DNS, however, IP addresses can be used.

Replace localhost with the FQDN or the IP in <ALLIANCE_HOME>/etc/users.properties, <ALLIANCE_HOME>/etc/users.attributes, and <ALLIANCE_HOME>/etc/custom.system.properties.

Tip

On linux this can be accomplished with a single command: sed -i 's/localhost/<FQDN|IP>/g' <ALLIANCE_HOME>/etc/users.* <ALLIANCE_HOME>/etc/custom.system.properties

Finally, restart the Alliance instance. Navigate to the Admin Console to test changes.

1.3. Configuring (Quick Start)

Set the configurations needed to run Alliance.

  1. In a browser, navigate to the Admin Console at https://{FQDN}:{PORT}/admin.

    1. The Admin Console may take a few minutes to start up.

  2. Enter the default username of admin and the password of admin.

  3. Follow the installer prompts for a standard installation.

    1. Click start to begin the setup process.

    2. Configure guest claims attributes or use defaults.

      1. See Configuring Guest Access for more information about the Guest user.

      2. All users are automatically granted these permissions.

      3. Guest users are not able to ingest data with more restrictive markings than the guest claims.

      4. Any data ingested that has more restrictive markings than these guest claims is not visible to Guest users.

    3. Select Standard Installation.

      1. This step may take several minutes to complete.

    4. On the System Configuration page, configure any port or protocol changes desired and add any keystores/truststores needed.

      1. See Certificates (Quick Start) for more details.

    5. Click Next

    6. Click Finish

1.4. Adding New User Roles

Users or user groups can be customized to enable or restrict access to specific certain system functions. Define a custom role and assign it to users who need specific access.

For an example, limit the replication admin view to users with a sr_analyst role.

Define a new role

  1. Navigate to the Admin Console.

  2. Navigate to the Security app.

  3. Navigate to the Configuration tab.

  4. Select the Web Context Policy Manager Configuration.

  5. Select Required Attributes.

  6. Define the contexts to be restricted.

    1. Enter <CONTEXT>={http://schemas.xmlsoap.org/ws/2005/05/identity/claims/role=<ROLE_NAME>

      1. For example, enter /admin/replication={http://schemas.xmlsoap.org/ws/2005/05/identity/claims/role=sr_analyst}

      2. Select the + sign to add another required attribute.

      3. Enter /admin/hub/graphql={http://schemas.xmlsoap.org/ws/2005/05/identity/claims/role=sr_analyst}

Assign the new role to users

  1. Add the new role (sr_analyst) to selected users in the users.properties file. Add the role to the line of each chosen user.

    1. For example, user1=password,sr_analyst

  2. Restart Alliance to apply the changes.

    1. /app/bin/stop

    2. /app/bin/start

In the example given, the /admin/replication context is only accessible to users with the sr_analyst role. Other roles can be designated as needed by substituting the <CONTEXT> and the <ROLE_NAME> as needed.

1.5. Ingesting (Quick Start)

Now that Alliance has been configured, ingest some sample data to demonstrate search capabilities.

This is one way to ingest into the catalog, for a complete list of the different methods, see Ingesting Data.

1.5.1. Ingesting Sample Data

  1. Download a sample valid GeoJson file here This link is outside the Alliance documentation.

  2. Navigate in the browser to Intrigue at {secure_url}/search/catalog.

  3. Select the Menu icon (navigator icon) in the upper left corner

  4. Select Upload.

  5. Drag and drop the sample file or click to navigate to it.

  6. Select Start to begin upload.

Note

XML metadata for text searching is not automatically generated from GeoJson fields.

Querying from Intrigue ({secure_url}/search/catalog) will return the record for the file ingested:

  1. Select the Menu icon (navigator icon)and return to Workspaces.

  2. Search for the ingested data.

Note

The sample data was selected as an example of well-formed metadata. Other data can and should be used to test other usage scenarios.