This article will guide an experienced Windows 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 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 Windows installer from our Service Portal.
- Download and install a supported JDK on the server. For more information, please see JDK - Java Development Kit.
- Download and install the Microsoft Visual C++ 2010 Redistributable Package (x64). See https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads for more information on how to obtain and install this package.
- 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.zip?action=download
- Please note that software such as IIS or 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.
- 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
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.
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'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 DATABASE <NETXDB> COLLATE Latin1_General_100_CI_AS_SC_UTF8; GO - 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.
USE <NETXDB>; GO CREATE LOGIN <USERNAME> WITH PASSWORD = 'YourStrongPassword'; GO CREATE USER <USERNAME> FOR LOGIN <USERNAME>; GO - This database user should not be the database owner but should be in the db_owner role.
ALTER ROLE [db_owner] ADD MEMBER <USERNAME>; GO - 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.
- 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 <NETXDB> SET ALLOW_SNAPSHOT_ISOLATION ON ALTER DATABASE <NETXDB> 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 <NETXDB> 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 <NETXDB>.* 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.
- Run the NetX Windows installer using a Windows administrator account. Click Next to begin the setup wizard.
- Click I Agree to accept the License Agreement. Follow the prompts.
- Choose the location where you want to install the core NetX application files. Click Next. If you want to specify custom locations for constituents and other temp files, that can be done after installation.
- Select the path where you installed the Java Development Kit. The wizard will auto-detect this location for you, but if you have multiple versions installed, you will need to choose the correct path. Click Next.
- Click Install to begin the installation process.
- After the installation has been completed successfully, uncheck the Run NetX box and click Finish. Before you attempt to run the application, you must perform initial configuration tasks. If you left the checkbox checked, go to your Windows Services console and stop the NetX service.
-
Check the account that the NetX service uses to ensure it has the correct permissions. Open the Services console, right-click on the NetX service and click Properties.
-
Click the Log On tab. Under Log on as, ensure that the Local System option is selected. Note: If you want to use Local Service or a custom service account instead, you will need to grant those accounts Full Control permissions to the NetX application directory before starting the service.
- Click OK to save changes and proceed to the next step: 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:
C:\Program Files\NetXposure\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:
C:\Program Files\NetXposure\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. "C:\Program Files\NetXposure\webapps\ROOT\WEB-INF\db\ip_mysql.sql")
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:
<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);<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);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 C:\Program Files\NetXposure\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 C:\Program Files\NetXposure\webapps\ROOT\WEB-INF\lib\.
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.
- Navigate to C:\Program Files\NetXposure\netx\config.
- 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://localhost: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: Database 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:
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.
- If you haven't done so yet, download Solr here: https://www.apache.org/dyn/closer.lua/lucene/solr/8.11.1/solr-8.11.1.zip?action=download
- Unzip the contents of the zip file.
- Create a Solr folder. In this example, we will create C:\Program Files\Solr.
- Copy the contents of the zip file into C:\Program Files\Solr.
- You now need to copy the Solr cores from the NetXposure application folder into the Solr folder. Copy the C:\Program Files\NetXposure\solr-cores\8\netx folder into C:\Program Files\Solr\server\solr\. When you are finished, you should have a C:\Program Files\Solr\server\solr\netx folder that contains the solr cores.
- Increase the default heap size to 2 GB. Open the C:\Program Files\Solr\bin\solr.in.cmd file and edit the following setting as such:
SOLR_JAVA_MEM="-Xms512m -Xmx2048m" - Now it's time to start Solr. Open Powershell, and type: & 'C:\Program Files\Solr\bin\solr.cmd' start
You should see the output as shown below.PS C:\Users\Administrator> & 'C:\Program Files\Solr\bin\solr.cmd' start INFO - 2019-04-02 16:01:48.056; org.apache.solr.util.configuration.SSLCredentialProviderFactory; Processing SSL Credent ial Provider chain: env;sysprop Waiting up to 30 to see Solr running on port 8983 Started Solr server on port 8983. Happy searching! - 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:
Month Savings 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
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 C:\Program Files\NetXposure\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 Requires restart: No |
| email.smtp_port |
The port that the server specified in email.smtp_host 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.
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.
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.
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:
C:\Program Files\NetXposure\netx\license
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 via the Windows Services Manager. Simply locate the NetX service, right-click and hit Start. You will also want to make sure that Solr is started if it isn't already running.
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 thumbnail 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 stderr.log file in the ticket.