Nexus Launcher Command Line
The Nexus launcher application has a complete command line interface. This interface can be used to create a new database as well as configure and launch a dedicated Nexus server instance. The command line greatly simplifies the creation and maintenance of Nexus instances located on remote server with no native GUI interfaces (e.g. AWS or Azure servers).
The command line closely follows the GUI interface. The entire interface can be a bit daunting, but is can be viewed using the -h option:
There are two required command line arguments, the location of the database and the operation to be taken. Additional command line arguments can be used to specify specific server configuration options. All commands require that the --db_directory command line option be specified. This must be the name of the directory where the Nexus database was (or is to be) created. Every operation (except create) begins by reading the configuration settings from the 'nexus.conf' file in the database directory. Next, the tool uses command line options to override various settings. For example '--instance_count 2' would change the number of server instances (for parallel report generator) to 2 from whatever had been set in the nexus.conf file. At that point, the tool will perform one of several operations using the augmented configuration options.
Potential actions include:
- create - create a new database
This is the only operation that does not read the nexus.conf file. In fact it requires that the target directory be empty. The operation will create a new, empty Nexus database in the directory. For example:
$ nexus_launcher create --db_directory /tmp/nexus_db
will create a new nexus databased in /tmp/nexus_db.
- save_config - save the nexus.conf file, applying any additional command line option changes
This operation is used to change configuration settings. After reading the nexus.conf file, the options specified on the command line will be used to override options that were read and the result is then written into the nexus.conf file. For example:
$ nexus_launcher save_config --db_directory /tmp/nexus_db --instance_count 3
will change the instance count setting to 3 and update the nexus.conf file.
- migrate - update the database to the most recent version of Nexus
When run, the database is updated to the latest version. This operation can take some time, particularly if 3D scenes are included in the database as they may need to be reprocessed. Note, this command is not generally needed as the operation is performed automatically with the start command.
- status - provide status output on the server
This operation checks to see what the status of any Nexus server associated with this database might be. For example, if no running server is associated with this database, the output might be:
$ nexus_launcher status --db_directory /tmp/nexus_db
or if a server is running:
$ nexus_launcher status --db_directory /tmp/nexus_db
- start - start a Nexus server. Note, this operation does not return until the server is stopped
This operation will start a new Nexus server for the database using the contents of the nexus.conf file along with any additional command line arguments. For example:
$ nexus_launcher start --db_directory /tmp/nexus_db --tray 1
Will start a new server (and not return until the server is stopped) and will include a control GUI in the system tray to allow the server to be monitored, launch the template editor, stop the server, etc.
- stop - shut down a running Nexus server
This operation will stop any server associated with the Nexus database.
- gui - run the nexus launcher GUI.
The launcher GUI can be used to interactively modify the various database options. This operation is the default, so if no other operation is specified, the GUI will be launched.
Nexus Server Architecture
In order to be able to discuss the Nexus server options, it is important to understand how a Nexus server works. In this section we describe the various processes and components of the Nexus server once launched.
The external URL interface is supplied by an instance of the nginx web server (nginx is included in the Nexus distribution). The nginx server is used to serve up media files for Nexus and serves as a load balancing interface for the actual Nexus server instances. There can be one more more actual Nexus server instances processing the various Nexus web requests. For example, with two instances, two reports may be generated at the same time. Each of these servers talk to the nginx server over their own ports. All Nexus metadata is stored in an SQL database. Currently SQLite and PostgreSQL are supported and the Nexus servers will communication with those databases. Finally, Nexus stores bulk data (e.g. images, movies, etc) in the local filesystem. The Nexus servers and nginx will both need to be able to access this filesystem (nginx needs only read-only access). Finally, there is one additional process that serves to monitor the health of the Nexus server. This service provides the mechanisms needed to shutdown the server, handle system tray operations, logging and other status functions.
Various server options control how ports are assigned to nginx and the Nexus servers as well as the number of servers and the database specifics.
- --instance_count ("Number of parallel servers to launch" in the GUI) specifies the number of Nexus Server instances that should be run.
- --server_port ("Port" in the GUI) specifies the port number that the nginx instance should listen on for incoming requests. If the port number is set to 0, a random, open port will be used. This port number can be queried using the command line status option (it will also be include in the URL reported by the GUI). If setting this to a non-zero value, care must be taken to ensure that the port does not conflict with other processes.
- --server_hostname ("Hostname" in the GUI) specifies the external hostname that the server will respond as. For example, if the Nexus server is configured to be accessed externally via the URL: http://my.nexusserver.com:80, the server hostname should be set to 'my.nexusserver.com'. The nginx server will only accept incoming requests that resolve to this hostname. A common mistake is setting the hostname to 'localhost' or '127.0.0.1' and enabling remote access (the GUI will present a warning in this situation). Some features of Nexus will not work in such a setup, unless the Nexus server has been hosted behind an appropriately configured proxy server. A rule of thumb is that the server hostname should be set to the name of the system as seen by other machines on the same network.
- --internal_base_port ("Base port for dynamic allocation" in the GUI) specifies the port number where Nexus will begin looking for unused ports when allocating ports for the Nexus servers and other components. In the above example, the server_port was set to 0, so Nexus started allocating ports for nginx and two Nexus servers. Since all of the ports starting at 8000 were available, it selected 8000, 8001 and 8002 for the components.
- --ssl_certificate (not available in the GUI) specifies the name of the ssl certificate file that nginx should use to serve up this connection. It will switch the Nexus server to use https instead of http. --ssl_key must also be specified.
- --ssl_key (not available in the GUI) specifies the name of the ssl key file that nginx should use to serve up this connection. It will switch the Nexus server to use https instead of http. --ssl_certificate must also be specified.
- --remote_session Nexus has the ability to embed applications that are capable of rendering (remotely) via the vnc protocol into reports. There are built-in interfaces for local EnSight and EnVision sessions as well as custom sessions defined in the external_services.json file. For embedded remote sessions to work, this option must be enabled. The built-in EnSight and EnVision local sessions can be enabled by setting --local_sessions_ensight and --local_session_envision options
- --local_sessions_ensight This option selects the maximum number of local instances of the EnSight application that can be running in embedded form simultaneously. These sessions are available for .ens file data items. --remote_session must be enabled in addition to setting this to a non-zero value.
- --local_sessions_envision This option selects the maximum number of local instances of the EnVision application that can be running in embedded form simultaneously. These sessions are available for .evsn file data items. --remote_session must be enabled in addition to setting this to a non-zero value.
- --server_name ("Name" in the GUI) specifies a string that should appear in the Nexus server "About" page or the system tray menu to describe this server.
- --postgresql_url ("Use postgresql", "Postgresql server hostname", "Postgresql server port", "Postgresql database name", "Username" and "Password" in the GUI) specifies that this Nexus server should use a PostgreSQL server as the database instead of an SQLite database. From the command line, all of these options are passed as a single string in the form: "postgresql://user:password@host:port/database". In the GUI, the individual fields have been broken out for easier editing. There are also buttons in the GUI to test the database connection and initialize the PostgreSQL database that will store the Neuxs database tables. Note, all Nexus databases begin as SQLite databases. Once created, they can be converted over to PostgreSQL.
- --acls ("Enable per-item ACL support" in the GUI) specifies that per-data item access control should be enabled for this server. See the ACLs section for details.
- --allow_remote_access Generally, Nexus servers are only accessible from the same system the server is running on (e.g. a local desktop session). This option allows the server to be accessed from machines other than the one the Nexus server is running on.
- --allow_iframe_embedding By default, Nexus prevents the HTML it generates to be displayed in <iframe>s for security. This option can be used to allow views of generated reports only from inside of an embedded <iframe>. Note, even after enabling this option, the content is still subjected to other <iframe> limits. For example, if one uses an SSL enabled server to serve up an <iframe> that contains a Nexus report and that report is not accessed via 'localhost' or an SSL enabled Nexus session, the content will still be blocked as one is not allowed to transition from SSL to non-SSL via the <iframe>. One last note, the admin functions (including login) are not supported in <iframe>s because of cookie limitations.
- --max_upload_size There is a limit on the size of a file/data item that can be uploaded to a Nexus server. By default, that limit is 5000 megabytes. This option allows that number to be adjusted from 1 to 20000 megabytes for a single data item.
- --tray (not available in the GUI, but will be automatically enabled if launching a server from the GUI). This option is not saved in the nexus.conf file and is only used if --start is the action. If enabled, the launcher application will attempt to create a system tray menu for controlling the server being started. Note that the host running the launcher instance must be capable of displaying GUIs for this option to work.
- --verbose ("Verbose logging" in the GUI). If enabled, additional diagnostic information will be logged when the server is run and the specifics of the configuration will be displayed on standard output. The logging information can be viewed from log files created in the Nexus database directory or in the system tray logging dialog.
- --debug (not available in the GUI). If enabled, the server will provide additional debugging information. This option should only be used when directed to by Ansys support.
- --stdout (not available in the GUI). If enabled, the server will log all output to stdout. This can be useful for debugging.