Wolfram Enterprise Private Cloud
Configuration

Use this Wolfram notebook to configure your Private Cloud system.

MouseOver

How to Use This Wolfram Notebook

Notes

Edit values, but not keys. Always maintain formatting and preserve quotes.

Values surrounded by a box, such as "example value",  indicates a required field. These must be edited in order to complete your configuration.

After editing, check to make sure the structure of each input is correct. A red annotation indicates an error.

Required Additional Actions

To complete the installation of your Private Cloud, you will need to make updates to external infrastructure systems (e.g. DNS configuration). These changes are covered in your pre-installation checklist.

Support Information

Private Cloud Support
   Email: privatecloud-support@wolfram.com
   Phone: +1-800-976-5309

Wolfram Language Support
  Email: support@wolfram.com
  Phone: +1-217-398-6500

MouseOver

Network Information

Base Domain

Set the base internet domain for your Private Cloud:

$CloudConfiguration["BaseDomain"]=
<|
"CloudBaseDomain" ->"\"
|>;

Example

Wolfram Enterprise Private Cloud within Example Company:

"CloudBaseDomain"->"wolfram.example.com";

Notes

CloudBaseDomain: The internet domain (or subdomain) that will be used to reach your Private Cloud. It will often be a subdomain of your corporate domain but can be any domain registered in DNS. The CloudBaseDomain should not contain the hostname. The value you choose will automatically be used to set the $CloudBase  property in your Private Cloud. $CloudBase= “https://www.CloudBaseDomain”.

In Wolfram Desktop clients, authorized users can access your Private Cloud by setting their $CloudBase or CloudBase-related options to this domain.

Files Modified

/etc/httpd/conf/httpd.conf

/etc/httpd/vhosts.d/one.conf

/etc/httpd/vhosts.d/www.conf

/etc/httpd/vhosts.d/develop.conf

/etc/httpd/vhosts.d/mathematica.conf

/etc/httpd/vhosts.d/datascience.conf

/etc/httpd/vhosts.d/lab.conf

/www/tomcat/base/8.0.24/conf/Catalina/localhost/app.xml

/etc/hosts

/wolframcloud/webapp/WEB-INF/client.properties

Master Node

The master node is the machine that controls any other nodes in your Private Cloud. Specify its hostname:

$CloudConfiguration["MasterNode"]=
<|
"MasterHostname" -> "master",
"MasterIPAddress" -> Automatic
|>;

Examples

"MasterHostname"->"headnode.your-domain.com";

For Wolfram Enterprise Private Cloud within Example Company, this would define the master node to have the fully-qualified domain name master.wolfram.example.com. Alternatively, this field can be set to a fully qualified domain name.

Notes

MasterHostname: In a single-machine configuration, the master node is your Private Cloud's only machine. It contains and runs all required services. In a larger-scale system, the master node acts as the controller for all other nodes. It runs all services except Wolfram Language kernels, which run on separate compute nodes to allow more concurrent users.

MasterIPAddress: This is the IP address of your Private Cloud’s master node. By default, it will be set to the IP address for the machine running the configuration notebook, but can be set to a different machine.

Files Modified

/etc/hosts

/etc/httpd/conf/httpd.conf

/etc/httpd/vhosts.d/www.conf

/etc/sysconfig/network

Cluster Nodes

The cluster nodes are the machines that run the Wolfram Language kernels. Specify their hostnames and IP addresses.

$CloudConfiguration["ClusterInformation"]=
<|
"ClusterNodeInformation" -> <||>
|>;

Examples

"ClusterNodeInformation"-><|"cmp-1" -> <|"IPAddress" -> "10.0.3.4"|>|>;

For Wolfram Enterprise Private Cloud within Example Company, this would define a compute node to have the fully-qualified domain name cmp-1.wolfram.example.com and IP Address 10.0.3.4 . Alternatively, this field can be set to a fully qualified domain name.

Notes

ClusterNodeInformation: In a single-machine configuration, the master node is your Private Cloud's only machine, so this configuration can be set to an empty Association.

Files Modified

/etc/hosts

/etc/httpd/conf/httpd.conf

/etc/httpd/vhosts.d/www.conf

/etc/sysconfig/network

MouseOver

How to Use This Wolfram Notebook »

SSL Certificates

⚠ Required Additional Actions
 You must place your SSL certificates and keys in the following directory: “/wolframcloud/ssl/”.

$CloudConfiguration["SSLCertificates"]=
\[LeftAssociation]
"IntermediateCertificate"->""
\[RightAssociation];

Notes

IntermediateCertificate: This is an optional field that should contain the filename of your intermediate certificate should you have one. This certificate also needs to be placed in “/wolframcloud/ssl/”.

Files Modified

/etc/httpd/conf/httpd.conf

MouseOver

How to Use This Wolfram Notebook »

Mail Settings

Mail Host

Wolfram Enterprise Private Cloud uses a local mail system for the Wolfram Language SendMail function. You should ensure that your enterprise mail systems allow this mail to be delivered and do not, for example, tag it as spam. Set the mail host and authentication information through which emails sent from your Private Cloud will be routed:

$CloudConfiguration["MailHost"]=
<|
"SendMailHost" ->"\",
"SendMailUsername"->"",
"SendMailPassword"->""
|>;

Example

"SendMailHost"->"mail.example.com";
"SendMailUsername"->"cloud_user";
"SendMailPassword"->"changeme";

Notes

SendMailHost: Can either be a valid mail server address or be left empty. If you specify a mail server,  in your mail server’s settings,  you must also allow access to incoming mail from your Private Cloud’s hostname. If you leave SendMailHost empty, system emails may not reach your mailbox, instead being directed to spam or blocked entirely depending on the level of mail filtering.
SendMailUsername: The username of the systemwide account that will be used to relay mail over the mailhost. 
SendMailPassword:  The password of the account that will be used to relay mail over the mailhost.

Files Modified

/etc/postfix/main.cf

System Email

Give the From username or address that should appear in automated system emails:

$CloudConfiguration["SystemEmail"]=
<|
"SystemEmailFromAddress" -> "admin"
|>;

Examples

Set a username that will be automatically expanded to add the base domain of your Private Cloud to form a complete email address:

"SystemEmailFromAddress"->"cloud-admin";

If this is set to just a username, without an @ sign and domain, the CloudBaseDomain of your Private Cloud will be used to construct the full email address. As a result, automated system emails from your Private Cloud will then contain the following:
From: Wolfram Cloud <cloud-admin@wolfram.example.com>

Set the system email From address to a complete email address:

"SystemEmailFromAddress"->"cloud-admin@example.com"

Notes

SystemEmailFromAddress: This information is used for email display; no actual email account need necessarily be associated with the address given. You can use a valid email address if you want users to reply to automated system messages.

Files Modified

/www/tomcat/base/8.0.24/conf/Catalina/localhost/app.xml

/etc/httpd/conf/httpd.conf

Support Email Address

Set a username or complete email address for Private Cloud users to contact support.

$CloudConfiguration["SupportEmail"]=
<|
"SupportEmailAddress"-> "support"
|>;

Example

Set a username that will be automatically expanded to add the base domain of your Private Cloud to form a complete email address:

"SupportEmailAddress" -> "cloud-support"

If the CloudBaseDomain is set to “cloud.example.com”, this would be automatically expanded to “cloud-support@cloud.example.com”.

Set the support contact to a complete email address, which can use any domain:

"SupportEmailAddress" -> "cloud-support@example.com"

Notes

SupportEmailAddress: This will appear in the “About” dialog of the Private Cloud web interface.

Files Modified

/www/tomcat/base/8.0.24/conf/Catalina/localhost/app.xml

/wolframcloud/webapp/WEB-INF/client.properties

MouseOver

How to Use This Wolfram Notebook »

Account Settings

Specify the email domains and individual addresses that will be permitted for user accounts:

$CloudConfiguration["AllowedAccounts"]=
<|
"AllowedEmailDomains" -> Automatic,
"AllowedEmailAddresses"->""
|>;

Example

"AllowedEmailDomains"->"example.com, example.co.uk";
"AllowedEmailAddresses"->"john@example2.com, tom@example3.co.uk";

Notes

AllowedEmailDomains: In your Private Cloud, user accounts can be created for email domains set in this parameter. Input a comma-separated string of entries to allow account creation for multiple email domains within your organization.
AllowedEmailAddresses: In addition to accounts that fall within AllowedEmailDomains, to allow account creation for specific users, enter individual email addresses in this parameter. You can also limit your Private Cloud to only a select number of people by specifying emails here and leaving AllowedEmailDomains empty.

Files Modified

/www/tomcat/base/8.0.24/conf/Catalina/localhost/app.xml

/wolframcloud/webapp/WEB-INF/client.properties

MouseOver

How to Use This Wolfram Notebook »

Database Administration

Specify the username and password to be used for your Private Cloud’s internal databases:

$CloudConfiguration["CloudDatabase"] = 
<|
"DatabaseUsername" -> "db_user",
"DatabasePassword" -> "\"
  |>;

Notes

You are not required to change the default username for your databases; however, you must create a password.

Internal databases store such content as data about users, metadata about user files and OAuth authentication information. User files for your Private Cloud are stored in your Private Cloud filesystem, not in these databases.

Files Modified

/www/tomcat/base/8.0.24/conf/Catalina/localhost/app.xml

MouseOver

How to Use This Wolfram Notebook »

Wolfram Engine Settings

Kernel Assignments

The Wolfram Engine is a container for Wolfram kernels. Wolfram Enterprise Private Cloud maintains pools of kernels to handle different types of usage:

SessionKernelPool: Kernels for interactive sessions associated with cloud notebooks.

DeploymentKernelPool: Kernels for evaluations associated with creating and accessing deployments such as APIs, forms, etc.

ServiceKernelPool: Kernels for automated computations associated with scheduled tasks and related services.

You can specify how many kernels should be assigned to each pool (every pool must have at least one kernel):

$CloudConfiguration["KernelPools"]=
<|
"SessionPool"->2,
"DeploymentPool"->2,
"ServicePool"->2
|>;

The total number of kernels assigned must be equal to the number of instances of the Wolfram Engine that you can run according to your license agreement.

Note

The number of kernels assigned to each pool can be changed at any time in this notebook. Use the buttons at the end of the notebook to deploy these changes.

Examples

In a development organization with a license for 16 kernels expecting a high concurrency of Private Cloud users logged on, most of the kernels should be assigned to the SessionKernelPool:

<|"SessionPool"->13,"DeploymentPool"->2,"ServicePool"->1|>;

In supporting a deployed API or app (with a license for 32 kernels), the majority of the kernels can be assigned to the DeploymentKernelPool:

<|"SessionPool"->1,"DeploymentPool"->30,"ServicePool"->1|>;

In supporting a server that generates automated reports (with a license for eight kernels), most of the kernels can be assigned to the ServiceKernelPool:

<|"SessionPool"->1,"DeploymentPool"->1,"ServicePool"->6|>;

Files Modified

/wolframcloud/webapp/WEB-INF/MSPConfiguration.xml

Kernel Initialization

You might want kernels from each type of pool to have different initialization files evaluated at startup. To enable this, specify the full path to an initialization directory for each type of kernel pool. All .m or .wl files in these directories will be automatically evaluated when the specified type of kernel starts up.

$CloudConfiguration["KernelInit"]=
<|
"SessionKernelInitializationDirectory"->"",
"DeploymentKernelInitializationDirectory"->"",
"ServiceKernelInitializationDirectory"->""
|>;

Note

The files in these directories are read before the kernel sandbox is entered. Therefore, the directories do not have to be in a location that is accessible by the sandbox.

Files Modified

/wolframcloud/webapp/WEB-INF/WolframEngineConfiguration.m

Kernel Queue Limits

For the deployment kernel pool, you can configure the maximum number of requests waiting for an available kernel. Any requests made after this limit is reached will get an immediate response indicating the server is busy.

$CloudConfiguration["KernelQueueLimits"]=
<|
"DeploymentRequestQueueSize"->10
|>;

Examples

The queue size can be increased in order to prevent requests from being refused:

<|"DeploymentRequestQueueSize"->250|>;

If your application frequently hits this limit, some options are to reduce the number of requests, optimize the performance of the evaluations in the deployment kernel or scale up by adding more kernels.

Files Modified

/wolframcloud/webapp/WEB-INF/MSPConfiguration.xml

Evaluation Limits

The Wolfram Engine can impose constraints on how long any given evaluation is allowed to run before completing.

SessionEvaluationTimeLimit: Maximum allowed time for a single evaluation in an interactive notebook.

SessionEvaluationMemoryLimit: Maximum allowed memory for a single evaluation in an interactive notebook.

DeploymentEvaluationTimeLimit: Maximum allowed time for a single evaluation in deployed APIs, forms, etc.

DeploymentEvaluationMemoryLimit: Maximum allowed memory for a single evaluation in deployed APIs, forms, etc.

ServiceEvaluationTimeLimit: Maximum allowed time for a single evaluation related to a scheduled task.

ServiceEvaluationMemoryLimit: Maximum allowed memory for a single evaluation related to a scheduled task.

These time limits are specified in seconds:

$CloudConfiguration["EvaluationLimits"]=
<|
"SessionEvaluationTimeLimit"->3600,
"SessionEvaluationMemoryLimit"->2048,
"DeploymentEvaluationTimeLimit"->300,
"DeploymentEvaluationMemoryLimit"->2048,
"ServiceEvaluationTimeLimit"->300,
"ServiceEvaluationMemoryLimit"->2048
|>;

MouseOver

How to Use This Wolfram Notebook »

Wolfram Engine Security

Kernel Sandbox

$CloudConfiguration["KernelSandbox"]=
<|
"UseSandbox"->True,
"AdditionalReadDirectories"->"",
"AdditionalWriteDirectories"->"",
"AdditionalExecuteDirectories"->""
|>;

Notes

UseSandbox: A global switch to enable or disable all Kernel Sandbox restrictions.

AdditionalReadDirectories: A comma-separated sequence of readable directories, beyond the standard set always allowed in Private Cloud.

AdditionalWriteDirectories: A comma-separated sequence of writeable directories, beyond the standard set always allowed in Private Cloud.

AdditionalExecuteDirectories: A comma-separated sequence of executable directories, beyond the standard set always allowed in Private Cloud.

Files Modified

/wolframcloud/webapp/WEB-INF/WolframEngineConfiguration.m

Parallel Computing

Use the properties in this section to enable and configure parallel computing features of the Wolfram Language (ParallelEvaluate, ParallelMap, etc.)

$CloudConfiguration["ParallelComputing"]=
<|
"AllowParallelComputing"->False,
"ParallelComputeNodes"->"localhost",
"ParallelKernelsPerNode"->4,
"ParallelLinkHost"->Automatic
|>;

Notes

AllowParallelComputing: Whether to allow parallel functionality like ParallelEvaluate and ParallelMap. If False, the other properties in this section are ignored.

ParallelComputeNodes: Either “localhost” to enable parallel subkernels to run on the master node only, or a sequence of hostnames to use for the parallel subkernels, separated by commas. Example: “machine1.mycompany.com, machine2.mycompany.com”.

ParallelKernelsPerNode: The number of kernels to launch per node by default.

ParallelLinkHost: If the master node has more than one network address, the hostname of the interface to use for communication with the compute nodes. Automatic lets the WSTP library choose an interface.

Files Modified

/wolframcloud/webapp/WEB-INF/WolframEngineConfiguration.m

Scheduled Tasks

$CloudConfiguration["ScheduledTasks"] =
<|
"RestrictTasks" -> False
|>;

Notes

RestrictTasks: Disables ContinuousTask and schedules that run more frequently than hourly.

Files Modified

/wolframcloud/webapp/WEB-INF/WolframEngineConfiguration.m

J/Link Sandbox

Each Wolfram Engine kernel can launch a separate Java runtime to make use of Java libraries and capabilities via the standard J/Link connectivity feature. This separate Java runtime utilzes its own sandbox configuration. The default behavior tightly restricts the directories from which Java can read and write files, including class definitions.

$CloudConfiguration["JLinkSandbox"]=
<|
"JLinkUseSandbox"->True,
"JLinkSecurityDirectory"->"/var/tmp/JLink",
"JLinkAllowedIPs"->"",
"JLinkAdditionalLibraries"->"sun.security.*",
"JLinkAdditionalReadDirectories"->"",
"JLinkAdditionalWriteDirectories"->"",
"JLinkMaxHeapSize"->524288
|>;

Example

"JLinkAllowedIPs"->" *.wolfram.com, www.xyzcompany.com:80, 140.177.10.10, *.mycompany.com:100-200";

Notes

Most installations utilize the defaults specified.

JLinkUseSandbox: A global switch to turn off all J/Link sandbox restrictions.

JLinkSecurityDirectory: A working directory utilized for runtime configurations. It is not likely that you will need to modify this.

JLinkAllowedIPs: A comma-separated sequence of IPs or domains to allow outgoing TCP access. Leaving this empty will block all addresses. Using just a “*” means allow all addresses. You will need to include the IPs or domains of any databases that you would like to be able to access using DatabaseLink.

JLinkAdditionalLibraries: A set of allowed native Java libraries, beyond the standard set always permitted in the Private Cloud.

JLinkAdditionalReadDirectories: A comma-separated sequence of directories readable by the Java library, beyond the standard set always allowed in Private Cloud.

JLinkAdditionalWriteDirectories: A comma-separated sequence of directories writeable by the Java library, beyond the standard set always allowed in Private Cloud.

JLinkMaxHeapSize: Maximum allowed memory for the J/Link JVM heap, expressed in kilobytes.

Files Modified

/wolframcloud/webapp/WEB-INF/WolframEngineConfiguration.m

MouseOver

How to Use This Wolfram Notebook »

Branding

Organization Identity

Specify your organization’s name as a text string. Include a logo by giving the location of an image file.

$CloudConfiguration["OrganizationIdentity"] =
<|
"OrganizationName" ->"",
"OrganizationLogo" ->"/home/cloud/updater/configuration/templates/wolfram-private-cloud.png" 
|>;

Notes

OrganizationName: The value you specify will appear at the top of all Private Cloud pages. This must be a text string and can contain Unicode characters. It can also be left as an empty string (""), in which case no organization name will be displayed.

OrganizationLogo: Can be a GIF, JPG, or PNG. The maxmium recommended width is 1000 pixels and maximum recommended height is 200 pixels.

Example

<|
"OrganizationName"->"Icosahedron Inc.",
"OrganizationLogo"->"/wolframcloud/configuration/icosahedron_inc_logo.png"
|>;

Files Modified

/www/tomcat/base/8.0.24/conf/Catalina/localhost/app.xml

/wolframcloud/webapp/WEB-INF/client.properties

/etc/httpd/conf/httpd.conf

Custom Landing Page

Specify an optional landing page that will overwrite the default Wolfram Enterprise Private Cloud landing page by providing the path to your custom HTML file. If you do not wish to specify a custom page, leave this value unchanged.

$CloudConfiguration["CustomLandingPage"]=
<|
"CustomLandingPagePath"->""
|>;

Notes

The OrganizationLogo parameter mentioned above is only used for the default landing page. To use that logo on your custom landing page, you must include it in your custom HTML.

Example

<|
"CustomLandingPagePath"->"/var/html/customlandingpage.html"
|>;

Legal Notices

You can add links to your own terms of use and privacy policy for your Private Cloud. These links will appear in the About item of the Profile & Settings menu on Private Cloud session pages.

$CloudConfiguration["LegalLinks"]=
<|
"TermsOfUse"->None,
"PrivacyPolicy"->None
|>;

Notes

Wolfram legal notices will appear in your Private Cloud. If you do not want to add your own notices, leave the default setting of None for TermsOfUse and PrivacyPolicy.

Example

Include your own terms of use from http://www.examplecompany.com/termsofuse:

"TermsOfUse"->"http://www.examplecompany.com/termsofuse";

Files Modified

/www/tomcat/base/8.0.24/conf/Catalina/localhost/app.xml

/wolframcloud/webapp/WEB-INF/client.properties

MouseOver

How to Use This Wolfram Notebook »

Apply Configuration

CloudConfigurationGenerator`GenerateConfigurationGrid[]

Generate Configuration Files: Generates files but does not install them.

Install Configuration Files: Installs all generated files used upon Private Cloud start-up.

Restart System Services: Restarts your Private Cloud application to pick up any changes in configuration files. The restart process may take up to a minute, during which time your Private Cloud will be offline. Users will need to log in again after the restart. Private Cloud does not automatically notify users of a restart.

Reset Cloud: Resets your Private Cloud to its initial state, deleting all user accounts and deleting all user files therein.

Configuration Information

CloudConfigurationGenerator`GenerateInformationGrid[]

Notes

Print Summary: Prints a summary of the generated Private Cloud configuration.

Email Summary: Sends an email summary of the generated Private Cloud configuration.

Restoring Previous Configurations

Use these buttons to clear unsaved changes or to restore a previous configuration.

CloudConfigurationGenerator`GenerateRestoreGrid[]

How to Use This Wolfram Notebook »