Startup Folder Prepared by the Installer

This article gives an overview of what the DirX Access Installer writes into the startup folder of a newly deployed DirX Access Server instance, and which template files it uses to do so.

The startup folder is the only configuration channel of a freshly deployed server: its content is applied by the Direct Application of System Actions, Configuration and Shadow User Tree during the very first startup. Everything the installer prepares there is therefore an implicit application of the very same template files that an administrator can also apply explicitly later on, by copying them from the etc/templates folder, customizing them and placing them into the startup folder by hand.

Because the files are applied only on startup, the whole content of the startup folder can be reviewed, changed, extended or removed between the end of the installation and the first start of the DirX Access Server. This is the recommended point at which to adapt a deployment to the production environment.

Startup Folder Layout

The startup folder of an instance is located at {installation_folder}/Services/instances/{instance}/startup/ and contains:

Folder Content

config/

Configuration objects in the import/export format of the Config REST Web Service.

sysactions/

System actions in the format of the SysActions REST Web Service operations.

sut/

Users and groups of the shadow user tree in the export format of the SCIM 2.0 REST Web Service.

Each of these folders contains a used/ subfolder into which successfully applied files are moved.

Only the JSON files located directly in config/, sysactions/ and sut/ are read. The folders are not traversed recursively, so files placed in a subfolder - for example sysactions/crypto/ - are ignored. Subfolders can therefore be used to stage or archive files, but never to group files that are meant to be applied.

The files are applied in alphabetical order of their file names, with one exception: all files whose name starts with dxaDefault are applied first, before all the other files. This is why the default system trust generation takes place before the numbered template files, even though d sorts after a digit.

Sources of the Startup Content

The installer fills the startup folder from two different sources.

Static Default Files

These files are shipped with the product and are copied without any modification. They are applied on every deployment, regardless of the selected deployment approach:

File Purpose

config/dxaDefaultConfig.json

The default configuration objects needed to be able to start any DirX Access Services instance.

sysactions/dxaDefault1SysActionCryptoGenerateSystemTrust.json

Generation of the system trust keystore system.trust - the self-signed certification authority that signs all dependent DirX Access system keystores.

Both files are relevant only for the first instance that is connected to a given application repository. When further servers are deployed against the same application repository, the files must not be applied a second time.

Rendered Template Files

The rest of the content is produced from the template files located in {installation_folder}/Services/instances/{instance}/etc/templates/ (config/, sysactions/ and sut/ subfolders). For every template selected by the chosen deployment approach, the installer:

  1. Reads the template.

  2. Replaces all ${variable} placeholders with the values derived from the installation properties.

  3. Writes the result into the corresponding startup subfolder under the name {NN}_{template_name}, where {NN} is a two-digit sequence number starting at 01 that enforces the intended application order.

If any placeholder of a template cannot be resolved - typically because the corresponding installation property was left empty - the template is skipped and no file is written. This is how optional parts of the deployment, such as the User Repository configuration of a User-repository-less Deployment, are switched off.

Content per Deployment Approach

The templates are grouped into features that build upon each other, following the Initial Configuration approaches. The following sections list the templates in the order in which the installer numbers them.

Business-service-only Server

Prepared for the Business-service-only Server Approach, that is when only the “Deploy DirX Access Server instance” option is selected. This is the minimal content that every deployed instance receives.

Note that even this most basic approach already establishes the complete cryptographic chain of the server: the system trust is generated by the static default file, and the secure communication server keystore is derived from it by the template above and referenced by the crypto container of the HTTPS port assignment. See Crypto-material Management for how to replace this default chain with your own crypto material.

UI-configurable Server (DirX Access Manager)

Prepared for the Basic UI-configurable Server, that is when the “Deploy DirX Access Manager” option is selected additionally. The content of the Business-service-only Server is extended by the scripted-configurable, SPA and Manager features:

DirX Access Credentials Manager

Selecting the “Deploy DirX Access Credentials Manager” option appends the following templates, continuing the numbering of the previously deployed approach:

  • Configuration (startup/config/)

  • System Actions (startup/sysactions/)

    • dxaDeployWebAppScimRest.json

    • dxaDeployWebAppPluginCredentialsManager.json

The Credentials Manager can be deployed on top of the UI-configurable Server as well as on top of the Business-service-only Server. In the latter case the SPA Core application and the Config RESTful Web Service it depends on are added together with it.

Conditional Templates

Some templates are mutually exclusive or optional. The decision is taken by the installer from the installation properties:

Condition Effect

No User Repository properties are set (User-repository-less Deployment)

dxaConfigUserRepository.json and dxaConfigSubjectTemplate.json are not applied.

The initial administrator is resolved by RBAC policies (administration.username or administration.role.subject.template.attribute.name)

dxaConfigRbacAdministration.json is applied, dxaConfigReaAdministration.json is not.

The initial administrator is resolved by REA policies (administration.role.attribute.name / administration.role.attribute.value)

dxaConfigReaAdministration.json is applied, dxaConfigRbacAdministration.json is not.

The initial administrator is an account in the application repository (administration.username / administration.password)

dxaUserDirXAccessAdministrator.json is applied to startup/sut/.

Template Variables

The following placeholders are resolved by the installer. They are listed here as an overview; the individual template pages in Template Files state which of them a particular template uses.

Variable Derived from

${dxaInstanceName}

services.instance.name

${dxaServerId}

The generated identifier of the server configuration object.

${dxaServerHostName}

services.native.hostname

${loadBalancerHostName}

services.native.hostname - to be changed manually if the server is published under a different public name.

${dxaServerPort}

services.http.port.ssl

${dxaServerPortPlain}

services.http.port

${dxaServerCacheIpAddress}, ${dxaServerCacheStartPort}, ${dxaServerCacheCommPort}

The DirX Access Cache Server connection parameters.

${dxaClusterEnableAppRepoRoles}

Derived from the chosen administrator resolution.

${userRepoProviderUrls}, ${userRepoAdminDn}, ${userRepoAdminPassword}, ${userRepoSearchBase}

The user.repository.* properties.

${subjectTemplateLoginNameAttributeName}, ${subjectTemplateDxaRoleListAttributeName}

The Subject Template attribute names.

${adminRoleAttributeName}, ${adminRoleAttributeValue}

administration.role.attribute.name / administration.role.attribute.value

${dirxAccessAdministratorUserName}, ${dirxAccessAdministratorPassword}

administration.username / administration.password

${basicPasswordSource}, ${basicCorrelateUserAccounts}

Derived from the chosen administrator resolution.

Templates that are never rendered by the installer - for example the federation and OAuth keystore generation templates - keep their placeholders and have to be resolved manually before they are applied explicitly.

Adapting the Startup Folder Before the First Startup

Because the installer only prepares the files, the deployment procedure can still change them. The typical adaptations are:

  • Replacing a generated keystore by an imported one - for example exchanging dxaDefault1SysActionCryptoGenerateSystemTrust.json for a system action that imports an externally created system trust. See How to Set up the Production Environment.

  • Adjusting the rendered values - most notably ${loadBalancerHostName}, the DNS names of the secure communication server keystore and all default passwords.

  • Adding further templates - copied from etc/templates, customized and numbered so that they are applied after the templates they depend on.

  • Replacing the whole content by an exported target configuration - the recommended approach for production servers, as described in Initial Configuration.