NetX Installation Guide for Linux

This article will guide an experienced Linux server administrator through a new on-premise installation of the NetX web application in a production environment. For an overview of the resources and skillset required to successfully manage an on-premise NetX environment, please review our On-Premise Hosting GuidelinesIf you are a SaaS (hosted) customer, NetX sysadmins will be deploying your site and this guide will not be relevant. Contact sales@netx.net for more information on SaaS vs on-premise deployments.

Before you begin

Before you start the installation process, review the following questions to ensure you are ready to begin.

Question Answer
Is your database management system installed and ready to use? Please consult your database vendor for instructions on how to install the system and its supporting software. This step is outside of the scope of NetX support and will not be included in this article. Once it's installed, information on how to create your database for use with NetX is included in the steps below.
Do you have a valid NetX license file? If you need help obtaining a new license, please contact your account manager or email sales@netx.net.
Do you want to install more than one application server? Setting up a distributed NetX configuration is out of the scope of this guide. Please contact your account manager for assistance if you've purchased additional NetX server instances.
Are you using supported software to host NetX? See Supported Platforms for details on which operating systems, databases, and browsers are supported.
Is your environment sized adequately for performance? NetX System Requirements and NetX Sizing Guide can help you determine the resources needed to run NetX. If you need assistance with sizing your environment, please contact your account manager or sales@netx.net.
Is your asset storage provisioned? Asset/constituent storage space will vary depending on the expected size of your repository. If you want to use NAS or SAN for asset storage, gigabit connectivity is required.  For best performance, asset repository and related appFiles should be stored on dedicated physical/virtual volumes — NFS, SMB,  or other mounted volumes are supported.

Preparing your environment

The following tasks should be completed on your server(s) before installing the core NetX application, Please ensure that all prerequisite downloads (JDK, drivers, etc) are 64-bit.

  1. Download the NetX installation pack from our Service Portal.

  2. Download and install Oracle Java JDK 8 (64-bit) on the server. For more information on where to download the JDK and how to install it, please see JDK - Java Development Kit.

  3. Download a supported JDBC driver. For more information, see Supported JDBC Drivers.

  4. Download the Apache Solr search engine here: http://archive.apache.org/dist/lucene/solr/7.7.2/solr-7.7.2.tgz
  5. Please note that software such Apache HTTP server that may conflict on port 80 or other ports is not directly supported and must be correctly configured or removed by the customer prior to installation. NetX Support will not troubleshoot or assist with the configuration of third-party software.
  6. Antivirus, web filters, and proxies are not supported for use with NetX. Please disable, whitelist, or exclude NetX directories from any security configurations that can prevent NetX from functioning properly.

Installing NetX

Step 1: Create a database

In this step, you will configure your database server for use with NetX, create a blank database, and populate the database with the NetX schema.

Please refer to your database software vendor's instructions for how to properly install your database management system and its supporting software. This step is outside of the scope of NetX's support services.
Microsoft SQL Server MySQL

For the purposes of this tutorial, SQL Server is configured to run in Mixed Authentication mode. You can use Integrated Authentication with NetX with SQL Server; however, Integrated Authentication is outside the scope of NetX Support and NetX can not guarantee providing any support for it.

  1. Create a new database. Remember your database name (e.g. netx), as it will be used to configure NetX's connection to this database in subsequent steps.
  2. Create a database user which NetX will connect as (e.g. netxdbaccount). This user should be a SQL Server user and not a Windows or Active Directory account. Remember this username, as it will be used to configure NetX's connection to this database in subsequent steps.
  3. This database user should not be the database owner but should be in the  db_owner  role. To set up this access to the database,  go to Security > Logins, right-click on the user account you created in step 2, and click Properties. Once the user properties page appears, click on User Mapping. Check the box to create a mapping to your NetX database and check the db_owner box to set the role.



  4. Open the SQL Server Configuration Manager to ensure that TCP/IP is enabled on SQL Server and listening on the correct port (which is 1433 for a default SQL Server installation). If you choose to set this port number to something other than the default, make sure to remember the number as it will be used to configure NetX's connection to this database in subsequent steps.



  5. Open the SQL Server Management Studio and access the Query Console by right-clicking on the newly created database and selecting New Query. Execute the following commands to set the isolation level. Don't forget to substitute the name of the database you created in step 1.
    ALTER DATABASE <dbname> 
    SET ALLOW_SNAPSHOT_ISOLATION ON
    
    ALTER DATABASE <dbname>  
    SET READ_COMMITTED_SNAPSHOT ON
Step 2: Install the core NetX application
  1. Create the directory where NetX will be installed

    mkdir /opt/netx
  2. Copy the NetX installation pack to your installation directory and unzip it

    mv /tmp/NetX-App-Complete-LATEST-master.zip /opt/netx/
    cd /opt/netx
    unzip ./NetX-App-Complete-LATEST-master.zip
  3. Ensure the installation scripts are executable

    chmod +x ./bin/*.sh
  4. Copy bin/setenv-default.sh to bin/setenv.sh and set the following environment variables. JAVA_HOME should be set explicitly to the path Java is installed at; the below example assumes that Java is installed under the /usr/java/ directory.

    cp bin/setenv-default.sh bin/setenv.sh
    cat >> ./bin/setenv.sh << EOF
    JAVA_HOME="/usr/java/latest"
    export JAVA_HOME;
    EOF
Step 3: Load the NetX Schema

After the application has been installed, you will need to populate an empty NetX schema in the database. This creates the tables, fields, and relationships that NetX uses to store data. Follow the instructions below for your chosen database vendor:

Microsoft SQL Server MySQL
  1. The script to load the NetX schema is located in the NetX application folder. Copy the ip_sqlserver.sql file to a location accessible by your database server. By default, this file is located here: 
    /opt/netx/webapps/ROOT/WEB-INF/db/ip_sqlserver.sql
  2. Open the SQL Server Management Studio. Right-click on your NetX database and click New Query. This will open the query console.
  3. Click File > Open > File
  4. Navigate to the ip_sqlserver.sql file that you copied in step 1 and click Open.
  5. Once the script has been loaded into the console, click Execute to run it. If the script ran successfully, you will see the following result:



Step 4: Load the initial admin user

After the schema has been loaded, you will need to set up an administrator-level user account that can log into the application after startup. Follow the instructions below for your chosen database vendor:

Microsoft SQL Server MySQL
Open the SQL Server Management Studio and access the Query Console by right-clicking on the newly created database and selecting New Query. Paste in the following query and substitute the required values with your own information. The following values need to be replaced in the query below:
<username>
<firstname>
<lastname>
<emailAddress>
<password>

Do not leave the < > brackets in with your values. After you have finished changing the values, execute the query.
INSERT INTO address (address_id, type, address_title, address_1, address_2, city, state, zip, country, organization, name, default_address) VALUES (1, 0, 'imageportal', '', '', '', '', '', '', '', '', 1);
INSERT INTO address_link (address_id, user_id, orderby) VALUES(1, 1, 1);
INSERT INTO exogen_user (user_id, login, name_1, name_2, name_3, name_4, email, password, creation_date, type, notify, password_access, phone_1, phone_2, phone_3, phone_4, organization, source_type, expiration_date)
VALUES (1, '<username>', '<firstname>', '', '<lastname>', '', '<emailAddress>', LOWER(CONVERT(NVARCHAR(64), HASHBYTES('SHA2_256', '<password>'), 2)), GETDATE(), 9, 1, '', '', '', '', '', '', 0, null);
Step 5: Load the database driver

If you haven't done so yet, you will need to download a JDBC driver for your chosen database vendor. See  Supported JDBC Drivers for more details on how to obtain the correct drivers.

Microsoft SQL Server MySQL
  1. When your download has finished, extract the contents and navigate to the jar file.



  2. Copy the mssql-jdbc-7.0.x.jre8.jar file and paste it into /opt/netx/webapps/ROOT/WEB-INF/.
Step 6: Connect NetX to the database

NetX's main system configuration file is called exogen-config.xml. To configure your database connection (and perform all subsequent configuration tasks in this article), you will need to edit the property values it contains. We recommend that you keep this file open in a separate window throughout the rest of the configuration for easy access. This tutorial assumes that you have created a database according to Step 1 above.

You might see other database-related properties in exogen-config.xml, we recommend that you leave the default values in place that ship with the install package unless you are specifically instructed to change them by NetX's onboarding or support staff.

Open /opt/netx/netx/config/exogen-config.xml in your text editor of choice and populate the values below according to your database system:

Property Description
db.type

This property specifies the type of database in use.

Value options: sqlserver, mysql

Requires restart? Yes

database.url

This property controls the JDBC URL. Pay close attention to the proper formatting, or your database connection will fail.

Microsoft SQL Server format:

jdbc:sqlserver://<hostname>:<port>;databaseName=<database>

Example:

jdbc:sqlserver://locahost:1433;databaseName=netx

If your database is running inside of a named instance, you can specify the instance in the URL like this: jdbc:

jdbc:sqlserver://localhost\instancename:1433;databaseName=netx

MySQL format:

jdbc:mysql://<hostname>:<port>/<database>

Example:

jdbc:mysql://localhost:3306/netx

Requires restart: Yes

database.user

This property controls the user account that is used to connect to the database

Value options: User account

Requires restart: Yes

database.password

This property controls the password for the user account that is used to connect to the database.

Value options: Password for the user account

Requires restart: Yes

This is what a correct property name and value entry looks like in the exogen-config.xml file:



Step 7: Install the Solr search engine

NetX relies on the Apache Solr engine to provide search capabilities. Starting in NetX 9, this engine is no longer bundled with the NetX install pack and must be installed separately. Since Solr is no longer managed by the NetX service, it will have to be manually started if the server reboots or is shut down. It is possible to run Solr as a Windows service using third-party solutions, but NetX cannot guarantee support for those configurations. Do so at your own risk.

  1. Download the Solr installation package from http://archive.apache.org/dist/lucene/solr/7.7.2/solr-7.7.2.tgz
  2. Extract the install_solr_service.sh script from the archive into the current directory:

    tar xzf solr-7.7.2.tgz solr-7.7.2/bin/install_solr_service.sh --strip-components=2
  3. Run the Solr installation script as root. By default, this script extracts the distribution archive into /opt, configures Solr to write files into /var/solr, and runs Solr as the solr user. You can customize the service name, installation directories, port, and owner using options passed to the installation script; to see available options, do sudo bash ./install_solr_service.sh -help. In the example below, we are running the install, but using the -n option so that the Solr service doesn't start after installation is complete.

    sudo bash ./install_solr_service.sh solr-7.7.2.tgz -n
  4. Copy the Solr cores from the netx application folder into the solr folder. Copy the /opt/netx/solr-cores/7/netx folder into  /var/solr/data/. When you are finished, you should have a  /var/solr/data/netx folder that contains the Solr cores.

    sudo -u solr cp -a /opt/netx/solr-cores/7/netx /var/solr/data/
  5. Increase the default heap size to 2 GB. Open the /etc/default/solr.in.sh file and edit the following setting as such:

    SOLR_JAVA_MEM="-Xms512m -Xmx2048m"
  6. The installation script creates a very basic init.d script so that you can control Solr using the service tool. Use the following commands to start the Solr service and report on its status:

    service solr start
    service solr status

    The status command should give some basic information about the running Solr node that looks like this:

    Solr process PID running on port 8983
    {
      "version":"5.0.0 - ubuntu - 2014-12-17 19:36:58",
      "startTime":"2014-12-19T19:25:46.853Z",
      "uptime":"0 days, 0 hours, 0 minutes, 8 seconds",
      "memory":"85.4 MB (%17.4) of 490.7 MB"}
  7. Now that Solr has successfully started, You should be able to log into the Solr admin console using the port number shown when you start the engine. Open a web browser and type 127.0.0.1:8983/solr/. Click Core Admin to verify that the core has loaded correctly.
  8. Finally, you must inform the NetX application where to find Solr. This is done by editing the exogen-config.xml file again and filling out a value for the property below:

  9. Finally, you must inform the NetX application where to find Solr. This is done by editing the exogen-config.xml file again and filling out a value for the property below:
    Property Description
    searchEngine.solrUrl

    This value tells NetX where to locate the Solr service.

    Value options: Solr service location

    Requires restart: Yes

Step 8: Configure storage and initial settings

Now that your database settings have been configured, it's time to set up your storage configuration and other important initialization settings. This is also done by editing the property values in the exogen-config.xml file. The locations configured below can be physical or virtual, as long as the path is understood by the server operating system. If the path is a mounted volume, please ensure that it will be automatically mounted before NetX is started in cases where the server is restarted.  For best performance, asset repository and related appFiles should be stored on dedicated physical/virtual volumes.

Property Description
storage.appFiles.directory

appFiles is the directory where asset constituents, views, versions, etc are stored. If you do not create this property, the application will default to /opt/netx/netx/appFiles. We recommend that you provision ample storage space for this directory, as it tends to grow in direct relation to your repository size.

Value options: appFiles location e.g. F:\appFiles

Requires restart: Yes

sys.repository_directory

The repository is the main storage location for original asset files. 

Value options: Repository location e.g. E:\repository

Requires restart: Yes

The following settings are also required for application initialization:

Property Description
email.smtp_password

Must only be set if SMTP server requires authentication

Value options: SMTP password

Requires restart: Yes

log.mail_from

This property sets the address from which emailed log entries originate.

Value options: Email address

Requires restart: Yes

log.rcpt_to

This property sets the address where log entries are mailed. We recommend that this value be set to your system administrator's email address so that they can monitor log errors as they appear.

Value options: Email address

Requires restart: Yes

sys.docroot_url

This is the URL that users will type in a browser to access your site.

Value options: URL

Requires restart: Yes

sys.site_domain

This is the FQDN (fully qualified domain name) of the server your site is hosted on.

Value options: FQDN

Requires restart? Yes

email.smtp

The email.smtp sets the SMTP hostname or IP address that NetX will use to send all email. Without this property, no email can be sent from the system.

Value options: SMTP hostname / IP address

Requires restart: Yes

email.from

This email address is used as the From address for system-generated emails, such as import reports. When this property is configured, all user-generated emails such as collection sharing, etc will originate from the email address associated with the user's account. See Configuring NetX to Send Email for details.

Value options: Email address

Requires restart: Yes

email.smtp_username

Must only be set if SMTP server requires authentication

Value options: SMTP username

Requires restart: Yes

After configuring the necessary values, don't forget to save the exogen-config.xml file.

Step 9: Configure transcoding engines

After you have configured the basic application settings, you will now need to install and configure third-party software that is required to process images, videos, PDFs, etc. This process consists of installing transcoding applications and then creating properties that inform NetX of the path to the executable binaries. Until you install transcoding software, you will not be able to generate thumbnails, previews, and other constituent files in the system. For more information on transcoding engines and how to install them, see Supported Transcoding Engines.

Step 10: Load the license file

A valid license key file is required to run NetX, and will have been sent via email to the software purchaser or other designated recipient.

  1. Make sure that your license key file is not contained within a Zip archive; if so, please unzip that file before attempting to proceed. The license key file will have a “.license” file extension.
  2. Copy the license file into the following location: 
    /opt/netx/netx/license
Step 11: Save your configuration and start NetX

At this stage you should verify that the following tasks have been completed:

  1. NetX database created.
  2. NetX core application installed.
  3. NetX schema loaded into the database.
  4. Application administrator account created in the database.
  5. Database driver loaded into the NetX application folder.
  6. Database connection properties configured in exogen-config.xml.
  7. Solr search engine installed and configured in exogen-config.xml.
  8. Storage and misc settings configured in exogen-config.xml.
  9. Transcoding applications installed and related properties configured in exogen-config.xml.
  10. Valid license file has been loaded into the application.

After you have finished checking that all required properties have been properly configured in exogen-config.xml, save the file. You can now start the NetX service:

sudo /opt/netx/bin/startup.sh; tail -F /opt/netx/logs/catalina.out



Testing the installation

It's best to perform a few tests to ensure that the installation and configuration were successful:

  • Open a web browser and type http://127.0.0.1/
  • After installation of your transcoding software, upload a .jpg file and check to see if asset gallery and preview images are generated.
  • Also, check the status of the repository, you should be able to download files. This way you can ensure that the repository location is correct. If these checks fail, contact Support for assistance.
  • The Getting Started guide will teach you the basics of the NetX application.

Troubleshooting

If you have trouble starting the NetX service or loading NetX in a browser after initial configuration, the first place to check is the Tomcat log. This is usually located here: C:\Program Files\NetXposure\logs\stderr.log. Look for error messages in the logs that might indicate why Tomcat will not load. The most common reasons are:

  • Another application is already using port 80 on the server.
  • There is an issue with the JDK environment.
  • Missing files and/or libraries.
  • Engines are misconfigured.

If you need to submit a support ticket for assistance with your installation, please include a copy of the full catalina.out and exogen.log files in the ticket.

Was this article helpful?
0 out of 0 found this helpful