Xill4 configuration
Xill4 is mainly configured through a configuration file, but all settings can be overridden using environment variables. This configuration file can be distributed with Xill4, however, it is not recommended to include secrets in the configuration file, and environment variables should be used for those instead. For the full list of configuration properties, go to the Configuration properties section.
The environment secret is an exception. Due to its highly sensitive nature, it is only configurable through environment variables and not through the configuration file.
Configuration file
The configuration file supports either YAML or JSON format. By default, Xill4 will look for a configuration in the files config.yml, config.yaml, or config.json. The configuration file is optional when all required settings are already supplied through environment variables.
Loading configuration files
Configuration files can also be with a different name or from a different location by specifying it through the command line:
./xill4 -c my-config.yml
./xill4 -c ../some-other/folder/config.yml
If the configuration file at the specified location could not be found, the application will automatically fall back on trying to find it at the default location.
Example configuration
As an example, a configuration file in JSON and YAML format containing all available configuration properties (except XILL4_ENVIRONMENT_SECRET, learn why) can be found below. This example is only for illustrative purposed. In practice, a configuration file will only contain a handful of properties, as in most cases the default values for the optional properties suffice.
Example configuration with all available properties
- YAML
- JSON
# Set your Xill4 license key, and the host of the license server
license:
# Required, string
key: YOUR-KEY-HERE
# Optional, string, default: https://api.cryptolens.io
host: https://api.cryptolens.io
# Set information regarding the logging, what levels are logged and if the list of operations before failure is logged
logger:
# Optional, string, allowed: [simple, json], default: simple
type: simple
# Optional, boolean, default: true
printStacktrace: true
# Optional, list, allowed: [error, warn, info, debug, http, trace, audit], default: [error, warn, info, debug, http, trace, audit]
levels:
- error
- warn
- info
- debug
- http
- trace
- audit
# Set information regarding the MongoDB database connection
database:
# Required, string
connectionString: mongodb://username:password@localhost:27017/databaseName
# Optional, boolean, default: false
tls: false
# Optional, string, default: <not set>
ca: /path/to/ca.pem
# Optional, string, default: <not set>
cert: /path/to/cert.pem
# Optional, string, default: <not set>
key: /path/to/key.pem
# Set the location of the project files
project:
# Optional, string, allowed: [fs, mongo], default: fs
storageLocation: fs
# Optional, string, default: ./projects
path: ./projects
# Configure where the project environments are stored
environments:
# String, default: ./environments
path: ./environments
# Set the OpenAI API key for editor code suggestions
editor:
# Optional, string, default: <not set>
apiToken: YOUR-API-TOKEN
# Configuration for (Keycloak) authentication
auth:
# Optional, string, allowed: [none, oidc, test], default: none
type: oidc
# Optional, string, default: <not set>
configUri: http://localhost:8080/realms/example-realm/.well-known/openid-configuration
# Optional, string, default: <not set>
clientId: example-client
# Optional, string, default: <not set>
clientSecret: example-client-secret-123456
# Optional, string, default: <not set>
loginUri: http://localhost:8080/realms/example-realm/protocol/openid-connect/auth
# Optional, string, default: <not set>
redirectUri: http://localhost:3000/auth/callback
# Optional, string, default: <not set>
postLogoutRedirectUri: http://localhost:3000/logout/success
# Configure to what back-end the front-end is connected to
server:
# Optional, number, default: 8000
port: 8000
# Optional, string, default: localhost
host: localhost
# Optional, string, default: /
baseUrl: /
# Optional, string, default: /api
apiBaseUrl: /api
# Optional, boolean, default: true
corsEnabled: true
# Optional, boolean, default: true
logRequestErrors: true
# Optional, number, default: 1024
maxUrlLength: 1024
# Optional, string, default: en-GB
locale: en-GB
# Configure security features of components
security:
# Optional, list, default: <not set>
trustedDomains:
- trusted.com
# Optional, list, default: <not set>
workDirs:
- /path/to/trusted/folder
# Optional, list, default: <not set>
execPaths:
- /bin/trusted-binary
# Configure the maximum number of worker threads allowed
workers:
# Optional, number, default: 30
maxWorkers: 30
{
"license": {
"key": "YOUR-KEY-HERE",
"host": "https://api.cryptolens.io"
},
"logger": {
"type": "simple",
"printStacktrace": true,
"levels": [
"error",
"warn",
"info",
"debug",
"http",
"trace",
"audit"
]
},
"database": {
"connectionString": "mongodb://username:password@localhost:27017/databaseName",
"tls": false,
"ca": "/path/to/ca.pem",
"cert": "/path/to/cert.pem",
"key": "/path/to/key.pem"
},
"project": {
"storageLocation": "fs",
"path": "./projects"
},
"environments": {
"path": "./environments"
},
"editor": {
"apiToken": "YOUR-API-TOKEN"
},
"auth": {
"type": "oidc",
"configUri": "http://localhost:8080/realms/example-realm/.well-known/openid-configuration",
"clientId": "example-client",
"clientSecret": "example-client-secret-123456",
"loginUri": "http://localhost:8080/realms/example-realm/protocol/openid-connect/auth",
"redirectUri": "http://localhost:3000/auth/callback",
"postLogoutRedirectUri": "http://localhost:3000/logout/success"
},
"server": {
"port": 8000,
"host": "localhost",
"baseUrl": "/",
"apiBaseUrl": "/api",
"corsEnabled": true,
"logRequestErrors": true,
"maxUrlLength": 1024,
"locale": "en-GB"
},
"security": {
"trustedDomains": [
"trusted.com"
],
"workDirs": [
"/path/to/trusted/folder"
],
"execPaths": [
"/bin/trusted-binary"
]
},
"workers": {
"maxWorkers": 30
}
}
Configuration through environment variables
Settings from the configuration file can be overwritten through the systems environment variables or by adding them to an .env file located in the applications root directory. Each setting from the configuration file has an environment variable counterpart, denoted with the XILL4_ prefix, followed by the configuration group and then the property name. See the full list of configuration properties to find the environment variable counterpart of each setting.
Setting environment variables
Environment variables can be specified either temporarily or persistent and in various ways. The recommended method is by using the System Properties window, but that is only available on Windows.
Temporarily through command line or terminal
The quickest way to temporarily set environment variables is by using the systems built-in terminal or command prompt:
- Windows
- PowerShell
- Linux
set XILL4_LICENSE_KEY=$value
$env:XILL4_LICENSE_KEY="value"
export XILL4_LICENSE_KEY=$value
After setting the environment variable(s), launch Xill4 from that same terminal or command prompt. The configuration options are applied automatically until the terminal or command prompt is closed.
System Properties window (recommended)
To permanently set environment variables on Windows, the System Properties window is used. It can be accessed by navigating to Control Panel > System and Security > System > Advanced system settings > Environment Variables. Through this window, new environment variables can easily be added and existing ones updated or deleted. After setting the environment variables, (re)start the application. The configuration options should be applied automatically.
Environment file
One or more environment variables can be specified in an .env file, located in the application root directory. Each line contains the environment variable name, followed by an equals sign = and the property value.
XILL4_SERVER_HOST="localhost"
XILL4_SERVER_PORT=8001
Make sure to never distribute this file with the Xill4 standalone binary, especially when it contains sensitive information such as the environment secret. For maximum security, use System Properties window where possible instead.
Specifying lists or arrays
Where YAML and JSON have built in array types for specifying lists, such as is needed for the logger.levels, security.trustedDomains, security.workDirs, and security.execpaths properties, environment variables do not. Instead, values are separated by commas ,, like so:
XILL4_LOGGER_LEVELS=error,warn,info
XILL4_SECURITY_TRUSTED_DOMAINS=example1.com,example2.com
Configuration properties
XILL4_ENVIRONMENT_SECRET
- Env:
XILL4_ENVIRONMENT_SECRET - Type:
string - Required
Secret used for the encryption of project environments. Make sure to keep this secret private and that it has sufficient length to not be easily guessed.
XILL4_ENVIRONMENT_SECRET=9ccd4a5aeacd1130747534aff369356f4c73afe31c9eaf7d
Due to the sensitive nature of the environment secret, this setting cannot be configured through the configuration file and must be defined through a environment variable instead.
license.key
- Env:
XILL4_LICENSE_KEY - Type:
string - Required
License key for Xill4 activation.
license:
key: ABCDE-FGHIJ-KLMNO
license.host
- Env:
XILL4_LICENSE_HOST - Type:
string - Optional, default:
https://api.cryptolens.io
Server to use for license key validation.
license:
key: <your-key>
host: https://custom.host.com
logger.type
- Env:
XILL4_LOGGER_TYPE - Type:
string, allowed:simple,json - Optional, default:
simple
Format of the Xill4 console output:
simple: Log messages are formatted as human readable text with color highlighting, if supported by the terminal applicationjson: Log messages are formatted as machine readable JSON objects.
logger:
type: simple
With the simple logger, messages may span multiple lines. With the json logger, each message only occupies a single line, making it ideal for parsing with external applications.
logger.printStacktrace
- Env:
XILL4_LOGGER_PRINT_STACKTRACE - Type:
boolean - Optional, default:
true
Print the stack trace to the console on runtime errors, not just the error message.
logger:
printStacktrace: true
logger.levels
- Env:
XILL4_LOGGER_LEVELS - Type:
string[], allowed:error,warn,info,debug,http,trace,audit - Optional, default:
[error, warn, info, debug, http, trace, audit]
Message types to output to the console. By specifying a subset (e.g., [error, warn, info]), only those message types are printed. The other message types are suppressed.
logger:
levels:
- error
- warn
- info
- debug
- http
- trace
- audit
database.connectionString
- Env:
XILL4_DATABASE_CONNECTION_STRING - Type:
string - Required
MongoDB connection string pointing to the database that can by used by Xill4 to store logs and, if configured, project files. If your MongoDB instance uses TLS, the options database.tls, database.ca, database.cert, and database.key have to be set as well.
database:
connectionString: mongodb://username:password@localhost:27017/databaseName
# When MongoDB uses TLS:
tls: true
ca: /path/to/ca.pem
cert: /path/to/cert.pem
key: /path/to/key.pem
- See also:
database.tls,database.ca,database.cert,database.key,project.storageLocation
database.tls
- Env:
XILL4_DATABASE_TLS - Type:
boolean - Optional, default:
false
Use TLS for the MongoDB connection. If TLS is enabled, the options database.ca, database.cert, and database.key are sometimes required by the MongoDB server as well.
database:
connectionString: mongodb://username:password@localhost:27017/databaseName
tls: true
# If TLS is enabled, the following properties can be set as well:
ca: /path/to/ca.pem
cert: /path/to/cert.pem
key: /path/to/key.pem
- See also:
database.ca,database.cert,database.key
database.ca
- Env:
XILL4_DATABASE_CA - Type:
string - Optional
Path to the certificate authority file to trust.
database:
connectionString: mongodb://username:password@localhost:27017/databaseName
tls: true
ca: /path/to/ca.pem
cert: /path/to/cert.pem
key: /path/to/key.pem
- See also:
database.tls,database.cert,database.key
database.cert
- Env:
XILL4_DATABASE_CERT - Type:
string - Optional
Path to the digital certificate file that allows the MongoDB server to verify the identity of the Xill4 application when establish the encrypted network connection.
database:
connectionString: mongodb://username:password@localhost:27017/databaseName
tls: true
ca: /path/to/ca.pem
cert: /path/to/cert.pem
key: /path/to/key.pem
- See also:
database.tls,database.ca,database.key
database.key
- Env:
XILL4_DATABASE_KEY - Type:
string - Required, if
database.tls = true
Path to the digital key file that allows the MongoDB server to verify the identity of the Xill4 application when establish the encrypted network connection.
database:
connectionString: mongodb://username:password@localhost:27017/databaseName
tls: true
ca: /path/to/ca.pem
cert: /path/to/cert.pem
key: /path/to/key.pem
- See also:
database.tls,database.ca,database.cert
project.storageLocation
- Env:
XILL4_PROJECT_STORAGE_LOCATION - Type:
string, allowed:mongo,fs - Optional, default:
fs
Type of storage to use for the project and environment files:
mongo: Project and environment files are stored in the MongoDB database specified indatabase.connectionStringfs: Project and environment files are stored on the local file system at the location specified inproject.path
projects:
storageLocation: mongo
- See also:
database.connectionString,project.path
project.path
- Env:
XILL4_PROJECT_PATH - Type:
string - Optional, default:
./projects
Path to the folder to store projects in. If it does not exist yet, it will automatically be created. This property is ignored when project.storageLocation is set to mongo. To specify where environments must be stored within each project folders, set environments.path.
projects:
path: /home/user/projects
- See also:
project.storageLocation,environments.path
environments.path
- Env:
XILL4_ENVIRONMENTS_PATH - Type:
string - Optional, default:
./environments
Path to the folder to store environments in inside a project. This property is ignored when project.storageLocation is set to mongo. To specify where projects must be stored, set project.path.
projects:
storageLocation: fs
path: /home/user/projects
environments:
path: ./environments # Resolves to /home/user/projects/<project_name>/environments
The environments are always stored relative to the root of a projects. Providing an absolute path can lead to undefined behavior.
- See also:
project.storageLocation,project.path
editor.apiToken
- Env:
XILL4_EDITOR_API_TOKEN - Type:
string - Optional
OpenAI API token. Specify to enable AI-autocompletion in the code editor.
editor:
apiToken: YOUR-OPEN-API-TOKEN
auth.type
- Env:
XILL4_AUTH_TYPE - Type:
string, allowed:none,oidc,test - Optional, default:
none
Authentication type to use for Xill4. Specifying none will disable authentication. If authentication is enabled, the options auth.configUri, auth.clientId, auth.clientSecret, auth.loginUri, auth.redirectUri, and auth.postLogoutRedirectUri are required as well.
auth:
type: oidc
# If authentication is enabled, the following properties are required:
configUri: http://localhost:8080/realms/example-realm/.well-known/openid-configuration
clientId: example-client
clientSecret: example-client-secret-123456
loginUri: http://localhost:8080/realms/example-realm/protocol/openid-connect/auth
redirectUri: http://localhost:3000/auth/callback
postLogoutRedirectUri: http://localhost:3000/logout/success
- See also:
auth.configUri,auth.clientId,auth.clientSecret,auth.loginUri,auth.redirectUri,auth.postLogoutRedirectUri
auth.configUri
- Env:
XILL4_AUTH_CONFIG_URI - Type:
string - Required, if authentication is enabled
Uri of the OpenID Connect well-known configuration endpoint.
auth:
type: oidc
configUri: http://localhost:8080/realms/example-realm/.well-known/openid-configuration
clientId: example-client
clientSecret: example-client-secret-123456
loginUri: http://localhost:8080/realms/example-realm/protocol/openid-connect/auth
redirectUri: http://localhost:3000/auth/callback
postLogoutRedirectUri: http://localhost:3000/logout/success
- See also:
auth.type
auth.clientId
- Env:
XILL4_AUTH_CLIENT_ID - Type:
string - Required, if authentication is enabled
Client ID created in the authentication provider for Xill4. Used by the authentication provider together with the auth.clientSecret to verify the login request came from Xill4, and not an unauthorized application.
auth:
type: oidc
configUri: http://localhost:8080/realms/example-realm/.well-known/openid-configuration
clientId: example-client
clientSecret: example-client-secret-123456
loginUri: http://localhost:8080/realms/example-realm/protocol/openid-connect/auth
redirectUri: http://localhost:3000/auth/callback
postLogoutRedirectUri: http://localhost:3000/logout/success
- See also:
auth.type,auth.clientSecret
auth.clientSecret
- Env:
XILL4_AUTH_CLIENT_SECRET - Type:
string - Required, if authentication is enabled
Client secret created in the authentication provider for Xill4. Used to verify that the auth.clientId actually belongs to Xill4.
auth:
type: oidc
configUri: http://localhost:8080/realms/example-realm/.well-known/openid-configuration
clientId: example-client
clientSecret: example-client-secret-123456
loginUri: http://localhost:8080/realms/example-realm/protocol/openid-connect/auth
redirectUri: http://localhost:3000/auth/callback
postLogoutRedirectUri: http://localhost:3000/logout/success
- See also:
auth.type,auth.clientId
auth.loginUri
- Env:
XILL4_AUTH_LOGIN_URI - Type:
string - Required, if authentication is enabled
Uri of the authentication provider login page.
auth:
type: oidc
configUri: http://localhost:8080/realms/example-realm/.well-known/openid-configuration
clientId: example-client
clientSecret: example-client-secret-123456
loginUri: http://localhost:8080/realms/example-realm/protocol/openid-connect/auth
redirectUri: http://localhost:3000/auth/callback
postLogoutRedirectUri: http://localhost:3000/logout/success
- See also:
auth.type
auth.redirectUri
- Env:
XILL4_AUTH_REDIRECT_URI - Type:
string - Required, if authentication is enabled
Uri of endpoint the authentication provider redirects to after a successful login. This endpoint should handle the temporary authentication code that is provided by the authentication provider and complete the authentication process.
auth:
type: oidc
configUri: http://localhost:8080/realms/example-realm/.well-known/openid-configuration
clientId: example-client
clientSecret: example-client-secret-123456
loginUri: http://localhost:8080/realms/example-realm/protocol/openid-connect/auth
redirectUri: http://localhost:3000/auth/callback
postLogoutRedirectUri: http://localhost:3000/logout/success
- See also:
auth.type
auth.postLogoutRedirectUri
- Env:
XILL4_AUTH_POST_LOGOUT_REDIRECT_URI - Type:
string - Required, if authentication is enabled
Uri of the page the user should be redirected to after being successfully logged out.
auth:
type: oidc
configUri: http://localhost:8080/realms/example-realm/.well-known/openid-configuration
clientId: example-client
clientSecret: example-client-secret-123456
loginUri: http://localhost:8080/realms/example-realm/protocol/openid-connect/auth
redirectUri: http://localhost:3000/auth/callback
postLogoutRedirectUri: http://localhost:3000/logout/success
- See also:
auth.type
server.port
- Env:
XILL4_SERVER_PORT - Type:
number - Optional, default:
8000
Port to expose Xill4 on.
# Navigate to http://localhost:8000 to reach Xill4
auth:
port: 8000,
host: localhost
baseUrl: /
- See also:
server.host,server.baseUrl
server.host
- Env:
XILL4_SERVER_HOST - Type:
string - Optional, default:
localhost
IP-address or hostname to expose Xill4 on.
# Navigate to http://localhost:8000 to show Xill4
auth:
port: 8000,
host: localhost
baseUrl: /
- See also:
server.port,server.baseUrl
server.baseUrl
- Env:
XILL4_SERVER_BASE_URL - Type:
string - Optional, default:
/
Base path of the front-end.
# Navigate to http://localhost:8000 to show Xill4
auth:
port: 8000,
host: localhost
baseUrl: /
- See also:
server.port,server.host
server.apiBaseUrl
- Env:
XILL4_SERVER_API_BASE_URL - Type:
string - Optional, default:
/api
Base path of the API endpoint.
# API accessible at http://localhost:8000/api
auth:
port: 8000,
host: localhost
apiBaseUrl: /api
- See also:
server.port,server.host
server.corsEnabled
- Env:
XILL4_SERVER_CORS_ENABLED - Type:
boolean - Optional, default:
true
Include permissive Cross-Origin Resource Sharing headers in HTTP requests to allow loading of resources from foreign origins on the front-end.
auth:
host: localhost
corsEnabled: false # Restrict resource access on the front-end to http://localhost/* only
- See also:
server.host
server.logRequestErrors
- Env:
XILL4_SERVER_LOG_REQUEST_ERRORS - Type:
boolean - Optional, default:
true
Output errors that occur during request handling to the console with level error and include a stacktrace. If disabled, (failed) requests are still logged at the http level, but these only contain the HTTP status code and message.
logger:
level:
- error
- warn
- info
# - debug
# - http
# - trace
# - audit
server:
logRequestErrors: true # Even though `http` messages are disabled, request errors are still shown now in the console with severity `error`
- See also:
logger.levels
server.maxUrlLength
- Env:
XILL4_SERVER_MAX_URL_LENGTH - Type:
number - Optional, default:
1024
Maximum length of an URL before discarding it. This is used to prevent (accidentally) overloading the server with oversized payloads.
server:
maxUrlLength: 1024
server.locale
- Env:
XILL4_SERVER_LOCALE - Type:
string - Optional, default:
en-GB
Locale to use by the server. Affects date and time format of the log messages in the log panel.
server:
locale: nl-NL
The formatting of the timestamp in the application logs (i.e., terminal output) is unaffected by the locale setting and always uses the ISO 8601 format instead.
security.trustedDomains
- Env:
XILL4_SECURITY_TRUSTED_DOMAINS - Type:
string[] - Optional
Domains allowed to access from the HTTP Request component. Leave undefined to allow access to all domains. Set to an empty list to disable the HTTP Request component.
security:
trustedDomains: [] # This will block access to all domains and effectively disables the HTTP Request component
Subdomains are automatically allowed, so when configuring example.com as trusted, api.example.com is automatically considered trusted as well. When only specifying api.example.com explicitly as trusted, requests to example.com will be denied.
security.workDirs
- Env:
XILL4_SECURITY_WORK_DIRS - Type:
string[] - Optional
Path to folder or files on the file system that can be accessed by components. When access to a folder is granted, access to all its subfolders is automatically granted as well. Leave undefined to allow components to access to the entire file system. Set to an empty list to disable file system access for the components altogether.
security:
workDirs: [] # Disables file access completely
This setting restricts filesystem access for all components, including database or content store components. Make sure that all the certificate files used by components are whitelisted as well.
security.execPaths
- Env:
XILL4_SECURITY_EXEC_PATHS - Type:
string[] - Optional
Path to applications and scripts that can be executed by the Exec component. Leave undefined to allow execution of all applications and scripts. Set to an empty list to disable the Exec component.
security:
execPaths: [] # This will block access to all applications and scripts and effectively disables the Exec component
Applications that are included in the system path can be shortened, for example 7z instead of C:\Program Files\7zip\7z.exe. However, when using shortened notation, the Exec component must use it as well. Similarly, when specifying the full path to an application or script, the Exec component must use the full path too.
workers.maxWorkers
- Env:
XILL4_WORKERS_MAX_WORKERS - Type:
number - Optional, default:
30
Maximum number of worker processes to be created, i.e., maximum number of concurrently turned-on flows.
workers:
maxWorkers: 30