Tutorial: Working with ENVI Servers Tutorial
ENVI Servers allow you to run several ENVI tasks or models in the background at the same time, either on your computer or across multiple computers on the network. When you run processes, or jobs, in the background, you can continue to work in ENVI without having to wait for each job to finish, and you can even close ENVI and the jobs will continue to run. You can monitor the status of processes and view the results when each job is complete.
See the following sections:
Start an ENVI Server
You can start an ENVI Server to run locally on your computer, or you can start an ENVI Server that can be used remotely by other ENVI users.
You can also run a script to start an ENVI Server using the StartENVIServer task.
Start an ENVI Server for Local Use
To start an ENVI Server that will be used locally on your computer:
- In ENVI, choose one of the following:
- From the ENVI main menu bar, select Server > Start ENVI Server.
- From the ENVI Modeler menu bar, select Server > Start ENVI Server.
The Start ENVI Server dialog appears.
-
Enter the Port number for the ENVI Server to listen to. The default is 9191.
If port 9191 is already in use and you want to add another local ENVI Server, toggle the up/down arrow buttons next to the field to find an available port.
- Enter the Workspace folder where the server output results will be saved. The default is a local directory on your computer.
- Set how many Workers to run in parallel on the local ENVI Server. The default is 4. Additional jobs will wait in the queue until one of the workers becomes available. You can change this to a different value, or to set no limit on the number of workers, enter "-".
-
From the Engine drop-down list, select which processing engine to use. The choices are:
- IDL Runtime: (default) Executes pre-compiled code.
- IDL: Allows source code compilation. This option requires a valid IDL license.
-
From the Log Level drop down list, severity of log messages written to both stdout and the log file with one of the following:
- Critical
- Error
- Warning
- Info
- Debug
- Select Yes for Clean Session if you want to start the engine with a fresh instance and default preferences. If set to No, the engine will run using the current ENVI configuration and customizations.
- Leave Public set to No since this will be a local ENVI Server. Only your computer can submit jobs to this server.
- Leave Secure Connection set to No.
- If you want the server to continue running after ENVI closes, set the Persistent parameter to Yes. This parameter is ignored if Install as a Service is set to Yes.
- Set Install as a Service to Yes if you want your local server to be installed as a service.
- Click OK. The local ENVI Server is ready to accept processing jobs.
- From the ENVI main menu bar, select Server > Manage ENVI Servers. In the Manage ENVI Servers dialog that appears, the local server, http://localhost:9191, should be included in the list.
Start an ENVI Server for Remote Use
You can configure one or more ENVI Servers to be used as network resources for distributed processing. For example, you may have a local ENVI Server and three additional ENVI Servers on a network. You can scale jobs even further by sending them to multiple, remote computers working in parallel so that you can continue to work with ENVI your computer. This is a good option if the remote computers have more powerful resources that will result in faster completion times for jobs.
When you submit a job to a remote ENVI Server, you are using a resource that might be shared with other users. When you run jobs, be aware of their size and how much time you will use on that computer.
An ENVI Server that will be used remotely requires the following:
- A Windows or Linux operating system. All ENVI Servers must use the same operating system so they can access the shared data using the same network paths.
- An installation of ENVI and any additional modules that might be run on the server.
- A valid license for ENVI and any additional modules.
- The input data must be placed in a shared location that the servers can access.
- If custom tasks will be used in any jobs, they must be installed on the remote server.
To start an ENVI Server for use on the network:
- Make note of the external URL of the computer; you will need this information later.
-
Use the steps from the previous section to start a server that can be used by others. For the following parameters, use these settings:
- Workspace: Enter the network location where the shared data is stored.
- Public: Set to Yes.
- Install the Server as a Service: If you set this parameter to Yes, make sure the owner of the service has the appropriate read/write permissions to the Workspace location.
- Click OK. The ENVI Server is started and ready to accept processing jobs.
Use the steps in Connect a Client to a Remote ENVI Server to make the remote ENVI Server available on a client computer.
Use the steps in Run Jobs to send jobs to an ENVI Server.
Start an ENVI Server from the Command Line
To start an ENVI Server without needing to start ENVI or IDL first, you can start the server from the command line.
ENVI Server is a self-contained Python script (server.py). Run it with the Python interpreter that ships with ENVI/IDL. The interpreter already includes all required packages (flask, waitress, psutil), so no separate installation is needed.
For Linux and Mac users: The examples in this section use Windows paths; substitute the Windows installation directories with you Linux or Mac installation directories.
Python interpreter (ENVI 6.x / IDL 9.x):
"C:\Program Files\NV5\ENVIxx\IDLxx\bin\bin.x86_64\idl-python\python"
Command Syntax
"C:\Program Files\NV5\ENVIxx\IDLxx\bin\bin.x86_64\idl-python\python" server.py --config <path-to-configuration.json> [options]
Arguments
|
Argument |
Required |
Description |
|
--config <path>
|
Yes
|
Path to configuration.json. Absolute or relative.
|
|
--workspace <path>
|
No |
Directory where job subdirectories are created. Supports UNC paths (\\server\share\workspace). Default: the directory that contains configuration.json.
|
|
--parent-pid <pid>
|
No |
PID of the process that launched the server (e.g. an IDL session). The server exits automatically when that process disappears. Omit when running as a standalone service.
|
configuration.json
The config file controls everything that is not a command-line flag.
Minimal Configuration
{
"envitask_engine_path": "C:\\Program Files\\NV5\\ENVIxx\\IDLxx\\bin\\bin.x86_64\\taskengine.exe"
}
Full Configuration Reference
{
"envitask_engine_path": "C:\\Program Files\\NV5\\ENVIxx\\IDLxx\\bin\\bin.x86_64\\taskengine.exe",
"port": 9191,
"workers": 4,
"min_free_memory_pct": 15.0,
"workspace_dir": "C:\\envi\\workspace",
"bind_localhost_only": false,
"log_level": "INFO",
"flags": "",
"https": {
"enabled": false,
"certfile": "C:\\envi\\certs\\server.crt",
"keyfile": "C:\\envi\\certs\\server.key"
}
}
Key Descriptions
|
Key |
Type |
Default |
Description |
|
envitask_engine_path
|
string |
(required) |
Full path to taskengine.exe. A .bat or .cmd path is also accepted; the server resolves it to the sibling taskengine.exe automatically.
|
|
port
|
int |
9191
|
TCP port the server listens on.
|
|
workers
|
int or null |
null
|
Maximum number of tasks that run concurrently. null (or omit the key) means unlimited: every submitted job starts immediately. Set to 1 to run one at a time, 4 for four parallel workers, etc.
|
|
min_free_memory_pct
|
float |
15.0
|
Minimum percentage of free RAM required before a new job is dispatched. When available memory falls below this threshold, queued jobs are held until memory recovers. At least one job always runs regardless of memory pressure, to prevent the queue from stalling. Set to 0 to disable memory backpressure entirely.
|
|
workspace_dir
|
string |
config file directory
|
Root directory for job files. Each job creates a numbered subdirectory here (0001/, 0002/, ...). Can also be set with --workspace on the command line, which takes precedence.
|
|
bind_localhost_only
|
bool |
false
|
true listens on 127.0.0.1 (same machine only). false listens on 0.0.0.0 (all network interfaces, reachable from other machines).
|
|
log_level
|
string |
"INFO"
|
Python logging level: "DEBUG", "INFO", "WARNING", "ERROR".
|
|
flags
|
string |
""
|
Extra flags passed verbatim to the task engine on every invocation (e.g. "--licenseHost=myserver"). Parsed with shell-style quoting.
|
|
https.enabled
|
bool |
false
|
Enable TLS. Requires certfile and keyfile.
|
|
https.certfile
|
string |
(none) |
Path to the PEM certificate file.
|
|
https.keyfile
|
string |
(none) |
Path to the PEM private key file.
|
Examples
Throughout these examples the Python path is abbreviated as idl-python\python for readability. Use the full path shown above when running the commands.
Simplest case - default port, unlimited workers, workspace next to config
"C:\Program Files\NV5\ENVIxx\IDLxx\bin\bin.x86_64\idl-python\python" server.py --config C:\envi\configuration.json
Custom workspace directory
"C:\Program Files\NV5\ENVIxx\IDLxx\bin\bin.x86_64\idl-python\python" server.py --config C:\envi\configuration.json --workspace D:\jobs
Limit to 2 concurrent tasks (set in config)
configuration.json:
{
"envitask_engine_path": "C:\\Program Files\\NV5\\ENVIxx\\IDLxx\\bin\\bin.x86_64\\taskengine.exe",
"workers": 2
}
"C:\Program Files\NV5\ENVIxx\IDLxx\bin\bin.x86_64\idl-python\python" server.py --config C:\envi\configuration.json
Non-default port, accessible only from localhost
configuration.json:
{
"envitask_engine_path": "C:\\Program Files\\NV5\\ENVIxx\\IDLxx\\bin\\bin.x86_64\\taskengine.exe",
"port": 8080,
"bind_localhost_only": true
}
"C:\Program Files\NV5\ENVIxx\IDLxx\bin\bin.x86_64\idl-python\python" server.py --config C:\envi\configuration.json
UNC workspace on a network share
"C:\Program Files\NV5\ENVIxx\IDLxx\bin\bin.x86_64\idl-python\python" server.py --config C:\envi\configuration.json --workspace \\fileserver\envi\workspace
HTTPS with a self-signed certificate
configuration.json:
{
"envitask_engine_path": "C:\\Program Files\\NV5\\ENVIxx\\IDLxx\\bin\\bin.x86_64\\taskengine.exe",
"https": {
"enabled": true,
"certfile": "C:\\envi\\certs\\server.crt",
"keyfile": "C:\\envi\\certs\\server.key"
}
}
"C:\Program Files\NV5\ENVIxx\IDLxx\bin\bin.x86_64\idl-python\python" server.py --config C:\envi\configuration.json
Workspace Layout
The workspace directory contains one subdirectory per job plus a bookkeeping file:
workspace/
_last_job_id <- high-water mark
0001/
job_0001_submitted.json <- request written at submit time
job_0001_executed.json <- result written when the task finishes
0002/
job_0002_submitted.json
job_0002_canceled.json <- written only if the job was canceled
...
Job IDs are zero-padded integers that always increase. After clearing completed jobs and restarting, IDs continue from where they left off (not from 0001) because the _last_job_id file records the highest ID ever issued.
Verify the Server is Running
Open a browser or run:
curl http://localhost:9191/reports/server-info
Or navigate to http://localhost:9191/dashboard for the web dashboard.
Stop the Server
Press Ctrl+C in the terminal window. If started with --parent-pid, the server also exits automatically when the parent process terminates.
Connect a Client to a Remote ENVI Server
When an ENVI Server is configured for use on the network, you can add it to the list of available servers on a client.
- On the client computer, choose one of the following:
- From the ENVI main menu bar, select Server > Add ENVI Server.
- From the ENVI Modeler menu bar, select Server > Add ENVI Server.
The Add ENVI Server dialog appears.
- In the Server URL field, enter the URL of the ENVI Server. The URL can be entered as the server name without the port number, if the server is using the default port 9191. If the ENVI Server is using a different port number, include it in the URL; for example:
remote_envi_server_name:port_number
-
Enter a custom Name to easily identify the server. The name will show in the Manage ENVI Servers dialog, when you select an ENVI Server to process a job, and as a tab name in the ENVI Job Console.
- Click OK to add the server.
Use the steps in the next section to send jobs to an ENVI Server.
To manage the list of ENVI Servers, see Manage ENVI Servers.
Run Jobs
You can run jobs on an ENVI Server from certain ENVI tool dialogs and from the ENVI Modeler.
-
To run a job from an ENVI tool dialog, click the drop-down arrow 
next to the OK button at the bottom of the dialog and select one of the following:
- Run Task on http://localhost:9191, to run the task on the local ENVI Server.
- Run Task on remote_envi_server_name, to run the task on a specific remote ENVI Server.
-
To run a job from the ENVI Modeler, click the drop-down arrow next to the Run button at the top of the ENVI Modeler, or select Server from the ENVI Server menu bar. Select one of the following:
- Run Model on http://localhost:9191, to run the model on the local ENVI Server.
- Run Model on remote_envi_server_name, to run the model on a specific remote ENVI Server.
When jobs are submitted, the ENVI Job Console appears so that you can monitor job progress and view results when processing is complete.
Manage ENVI Servers
You can add, edit, and remove ENVI Servers from the list of available servers, and you can view information about each server, including what versions of ENVI-related software it is running.
- Choose one of the following:
- From the ENVI main menu, select Server > Manage ENVI Servers.
- From the ENVI Modeler menu, select Server > Manage ENVI Servers.
The Manage ENVI Servers dialog appears, showing the ENVI Servers available for use on your computer.
- Manage the servers with the following:
- Click OK to exit.
See Also
ENVIServer (programming), ENVI Server REST API, Batch-Process Data on ENVI Servers, Visual Programming with the ENVI Modeler