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:
usage: nexus_launcher212.py [-h] [--db_directory database_directory]
[--ssl_key key_file] [--server_name "Name"]
Version 2021 R2: Configure/launch a Nexus server
operation 'start' : Start the server selected by the specified database directory.
'stop' : Shut down any server associated with the specified database directory.
'status' : Display the status of any server associated with the specified database directory.
'create' : Create a new Nexus database in the database directory.
'migrate' : Update the database schema to the latest.
'save_config' : Save the server configuration as the default for this database. Do not launch a server.
'gui' : start the launcher configuration editor GUI (default operation).
-h, --help show this help message and exit
Directory containing the Nexus database
Number of Nexus server instances to launch
Port number to run the server on. 0=select dynamically
Hostname to run the server on (external hostname)
Port number base to allocate server instances, etc. 0=select dynamically
Name of the SSL certificate file to encrypt the session with
--ssl_key key_file Name of the SSL key file to encrypt the session with
--server_name "Name" The human readable name to use for the database
URL to the PostgreSQL database to use: "postgresql://user:password@host:port/database"
Enable/disable per-item ACL functionality (default: false).
Enable desktop tray integration (default: false).
Enable verbose output (default: false).
Run the server in debug mode (default: false).
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:
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.
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.
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.
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
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.
This operation will stop any server associated with the Nexus database.
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.
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.