Configuration

Configuring Sanbox Runtime

Lumisan Sanbox Runtime has just one source for all its configuration. Configuration can be stored either as a file runtime.json in the working directory of the Runtime, or stored as a JSON string in the SANBOX_RUNTIME_CONFIG environment variable. The Runtime will first check to see if the aforementioned environment variable has a value. It will not use runtime.json if the environment variable is specified.

Any changes to configuration will not take effect until you restart Sanbox Runtime.

It is highly advised that you read the entirety of this article to maximize security and speed for your setup.

Default Configuration

You can use the default configuration if you are looking to just get started with Lumisan Sanbox and want to evaluate before you install on real infrastructure. The default configuration allows you to log in with Designer using the Access ID admin and Access Key admin.

Here is the default runtime.json configuration that is shipped with Sanbox Runtime:

{
"HttpWebServer": {
"UseForwardedHeaders": false,
"UseResponseCompression": true,
"RedirectWWW": false,
"KnownProxies": [],
"Https": {
"UseHttps": false,
"RedirectToHttps": true,
"UseCertStore": true,
"CertStoreName": "localhost",
"CertPath": null,
"Password": null,
"Port": 443
},
"Http": {
"Port": 80
},
"Security": {
"AllowAllMediaTypes": false
},
"GlobalHeaders": {
"Content-Security-Policy": "script-src 'self'",
"X-Frame-Options": "SAMEORIGIN",
"X-XSS-Protection": "1; mode=block",
"X-Content-Type-Options": "nosniff",
"Referrer-Policy": "no-referrer",
"X-Powered-By": "Lumisan Sanbox"
}
},
"Caching": {
"Type": "Memory",
"Enabled": true,
"CacheFiles": true
},
"Image": {
"ImageFilePath": "runtimeImage.sbimg",
"DoBackups": false,
"BackupFrequency": "@midnight",
"BackupRetentionCount": 10,
"BackupDirectory": "RuntimeBackups",
"AllowDeployments": false
},
"RuntimeAPI": {
"Enabled": false,
"APIKey": ""
},
"Designer": {
"AllowDesigner": true,
"AccessKeys": {
"admin": "admin"
},
"HostName": "0.0.0.0",
"Port": 50155,
"SecureServer": false,
"CertPath": "",
"PrivateKeyPath": ""
},
"JobProcessing": {
"ProcessJobs": true
},
"Environment": "Development",
"RunAsWindowsService": false,
"RunInBackground": false
}

Configuration Sections

HttpWebServer - object

This section applies to all HTTP related settings for Sanbox Runtime.

UseForwardedHeaders - true/false

Set this to true when the Runtime is behind a reverse proxy or load balancer that uses forward headers X-Forwarded-For and X-Forwarded-Proto. This allows Sanbox to preserve the scheme (HTTP/HTTPS) and remote IP address of incoming requests.

KnownProxies - string array

To be used only in conjunction with UseForwardedHeaders. You should specify one or more IP Addresses to use as allowed known proxies. For example, add 127.0.0.1 if the reverse proxy is on the same machine.

RedirectWWW - true/false

If true, causes the Runtime to redirect all requests to host www to non www. For example, with the Runtime behind example.org, www.example.org does a redirect to example.org. For more advance configuration or to redirect the base domain to www, we recommend you place Sanbox Runtime behind Nginx or Apache.

UseResponseCompression - true/false

Setting this true will cause Sanbox Runtime to compress requests for certain resources using content negotiation between the client and Runtime. Its advised not to use response compression when the Runtime is behind Nginx or Apache as they provide compression technologies slightly more robust than Sanbox's.

Https

Sub-section regarding HTTPS settings.

  • UseHttps - true/false - Set to true to enable HTTPS for the Runtime.

  • RedirectToHttps - true/false - For when Sanbox is installed as an edge server (not behind a reverse proxy), redirects all HTTP calls to HTTPS.

  • UseCertStore - true/false - When set to true, uses the personal X.509 store to locate a certificate. The certificate name being CertStoreName. CertPath and Password are not used when UseCertStore is true.

  • CertPath - string - File path to certificate to use. Certificates must be in .pfx format. Learn how to convert .pem to .pfx using openssl. UseCertStore must be false when this setting is true.

  • Password - string - Optional password to use for the file at CertPath, can be left empty or null if no password is required.

  • Port - number - Port used for HTTPS requests.

Http.Port - number

Port number to use for HTTP requests.

Security.AllowAllMediaTypes - true/false

When set to true, allows all media types to be processed by API workflows. When set to false, only JSON, XML, image, text, url encoded, and form types are allowed.

GlobalHeaders - dictionary

A dictionary of headers that will be added to every HTTP/HTTPS response made by the Runtime.

Caching - object

Caching controls the caching done in Sanbox Runtime.

Type - string

The type of caching medium to use, currently only a in memory cache is supported.

Enabled - true/false

Denotes whether caching is enabled. It is strongly recommended that this value is always true or performance will be degraded considerably.

CacheFiles - true/false

Indicates whether files uploaded to the Runtime via the Designer (Sanbox Files) are cached or not. Setting this to false is useful when your Runtime contains large or many files. For normal web content however, setting this to true yields better performance.

Image - object

This section applies to options surrounding the Runtime's image.

ImageFilePath - string

Relative or absolute file path to the location of the image file. If the file does not exist, Sanbox creates a demo image containing a landing page.

DoBackups - true/false

If true, indicates that the Runtime should backup the image on a schedule.

BackupFrequency - string

‚ÄčCron Expression denoting when to do image backups. Only applies if DoBackups is true.

BackupRetentionCount - number

The number of backups the Runtime should keep. Old backups are deleted. Only applies if DoBackups is true.

BackupDirectory - string

The absolute or relative directory path to where backups will be created. If the directory doesn't exist, its created. Only applies if DoBackups is true.

AllowDeployments - true/false

If true, then deployments are allowed via the Runtime API or Sanbox Designer.

RuntimeAPI

This section applies to the built-in Runtime API, used primarily for automatic deployments.

Enabled - true/false

If true, indicates that the Runtime API will be turned on at startup.

APIKey

The API Key used to access the Runtime API. See the automatic deployments article for more information.

Designer

This section applies to Sanbox Designer connections to this Runtime.

AllowDesigner - true/false

If true, indicates that the Runtime will listen for Designer connections. Its advisable to have this false for production instances where more security is desired.

AccessKeys - dictionary

Access keys are used to authenticate Sanbox Designers with the Runtime. They should be thought and treated as API keys and not username/passwords. For each entry, the property name is the access ID and the value the access key. You can have as many access id/key pairs as you wish. Access IDs should be unique, short, and given a human readable name. Access keys should be a random string or password and are encrypted at rest when entered in Sanbox Designer. Remember to change the default configuration.

HostName - string

The IP address or host name the designer service will listen on.

Port - number

The port number the designer service will listen on.

SecureServer - true/false

If true, indicates that all communication between the Runtime and Designer will be encrypted and secure. Visit the Securing Designer Connections article to learn more.

CertPath - string

Applicable only when SecureServer is true. Indicates the absolute or relative path to the public key certificate to secure Designer connections.

PrivateKeyPath - string

Applicable only when SecureServer is true. Indicates the absolute or relative path to the private key file to secure Designer connections.

JobProcessing.ProcessJobs - true/false

When true, indicates that Job workflows set to be ran on a schedule will be ran.

Environment - string

The environment that this Runtime is running in. This value can be any string, but if its Production, then the Runtime will make optimizations and hide uncaught errors from API / Web App consumers.

RunAsWindowsService - true/false

When true, indicates that the Runtime is running as a Windows Service. This must be set when the Runtime is running as a Windows Service.