NetX Installation Guide for Linux

Updated May 14, 2024 23:41

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 Guidelines. If 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.

Download the NetX installation pack from our Service Portal.
Download and install a supported JDK on the server. For more information, please see JDK - Java Development Kit.
Download a supported JDBC driver. For more information, see Supported JDBC Drivers.
Download the Apache Solr search engine here: https://www.apache.org/dyn/closer.lua/lucene/solr/8.11.1/solr-8.11.1.tgz?action=download
Note that software such as 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 before installation. NetX Support will not troubleshoot or assist with the configuration of third-party software.
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.

For 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't provide any assistance with this configuration.

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.
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.
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.
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.
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
```

As a MySQL superuser, run the mysql command. Create a database (e.g. netx). Remember your database name, as it will be used to configure NetX's connection to this database in subsequent steps.
```
CREATE DATABASE netx CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```
Create a database user which NetX will connect as (e.g. netxdbaccount). Remember this username, as it will be used to configure NetX's connection to this database in subsequent steps. Do not leave the < > brackets in with your values.
```
GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP,ALTER,REFERENCES,INDEX on <NETX>.* TO '<USERNAME>'@'<NETXDB_SERVER_HOSTNAME>' IDENTIFIED BY '<PASSWORD>';
flush privileges;
```
Edit the my.cnf file on your MySQL server (refer to http://dev.mysql.com/doc/refman/5.6/en/option-files.html for detailed instructions on editing my.cnf.) Locate the [mysqld] section in the file, and add or modify the following parameters:

Set the default storage engine to InnoDB:
```
[mysqld]
...
default-storage-engine=INNODB
...
```
Ensure the sql_mode parameter does not specify NO_AUTO_VALUE_ON_ZERO. Remove this line if it exists:
```
sql_mode = NO_AUTO_VALUE_ON_ZERO
```

Configure character set and collation settings:

[mysqld]
...
character-set-server=utf8mb4
...
collation-server=utf8mb4_unicode_ci

Specify the default authentication:

[mysqld]
default-authentication-plugin=mysql_native_password

Restart your MySQL service for the changes to take effect.

Step 2: Install the core NetX application

Create the directory where NetX will be installed
```
mkdir /opt/netx
```

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

Ensure the installation scripts are executable
```
chmod +x ./bin/*.sh
```
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:

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
```
Open the SQL Server Management Studio. Right-click on your NetX database and click New Query. This will open the query console.
Click File > Open > File
Navigate to the ip_sqlserver.sql file that you copied in step 1 and click Open.
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:

Copy the ip_mysql.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_mysql.sql
```
As a MySQL superuser, run the mysql command and type:
```
source /path/to/your/file.sql;
```
Where /path/to/your/file.sql is the full path to the ip_mysql.sql file (e.g. /opt/netx/webapps/ROOT/WEB-INF/db/ip_mysql.sql)

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:

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);

As a MySQL superuser, run the mysql command. In the following query, 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. When 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>', SHA2('<password>', 256), NOW(), 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.

When your download has finished, extract the contents and navigate to the jar file.
Copy the mssql-jdbc-7.0.x.jre8.jar file and paste it into /opt/netx/webapps/ROOT/WEB-INF/lib.

When your download has finished, extract the contents and navigate to the jar file.
Copy the mysql-connector-java-8.0.x.jar file and paste it into /opt/netx/webapps/ROOT/WEB-INF/lib.

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 keeping 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.

Copy /opt/netx/netx/config/default-exogen-config.xml to a new file named exogen-config.xml in the same directory. Open 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. This engine is not bundled with the NetX install pack and must be installed separately. Since Solr is not 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.

Download the Solr installation package here: https://www.apache.org/dyn/closer.lua/lucene/solr/8.11.1/solr-8.11.1.tgz?action=download.
Extract the install_solr_service.sh script from the archive into the current directory:
```
tar xzf solr-8.11.1.tgz solr-8.11.1/bin/install_solr_service.sh --strip-components=2
```
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-8.11.1.tgz -n
```
Copy the Solr cores from the netx application folder into the solr folder. Copy the /opt/netx/solr-cores/8/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/8/netx /var/solr/data/
```
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"
```

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:

SSolr process 1819 running on port 8983
{
"solr_home":"/opt/solr/solr-8.11.1/server/solr",
"version":"8.11.1 2f24e6a49d48a032df1f12e146612f59141727a9 - mayyasharipova - 2021-10-12 15:19:17",
"startTime":"2021-11-08T18:55:21.522Z",
"uptime":"2 days, 14 hours, 38 minutes, 47 seconds",
"memory":"349.8 MB (%68.3) of 512 MB"}

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.

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 URL (including the path to the NetX core) e.g. http://localhost:8983/solr/netx

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 the SMTP server requires authentication Value options: SMTP password Requires restart: No
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
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_host	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, e.g. mail.company.com Requires restart: No
email.smtp_port	The port that the SMTP server uses for SMTP communication. Value options: port number Default value: 25 Requires restart: No
email.smtp_username	Must only be set if the SMTP server requires authentication Value options: SMTP username Requires restart: No

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

Step 9: Install Redis

NetX uses Redis as a database, cache, and message broker for certain features. For instructions on how to install Redis and configure NetX to utilize it, see Installing Redis.

Step 10: 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 11: 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.

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.
Copy the license file into the following location:
```
/opt/netx/netx/license
```

Step 12: Save your configuration and start NetX

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

NetX database created.
NetX core application installed.
NetX schema loaded into the database.
Application administrator account created in the database.
Database driver loaded into the NetX application folder.
Database connection properties configured in exogen-config.xml.
Solr search engine installed and configured in exogen-config.xml.
Storage and misc settings configured in exogen-config.xml.
Transcoding applications installed and related properties configured in exogen-config.xml.
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 copies of the full catalina.out and exogen.log files in the ticket.

Before you begin

Preparing your environment

Installing NetX

Testing the installation

Troubleshooting

Articles in this section