Adding a new CLI parameter to initialize your server

Sometimes, there is a value in your server configuration that you do not want to hardcode. A good example of this is the password for your email account, should you have one enabled. Fortunately, due to the customizability of the server, it is possible to add such an option entirely through additions to your Components.js configuration. Below is an overview of the required additions. The example covers how to use a variable for the email account password, but it can be generalized to any situation.

For more details of how to configure the CLI system, have a look at the architecture documentation.

Although only a new CLI parameter is covered here, a new environment variable is also available as described in the server initialization documentation.

Creating the variable

For every variable in your configuration, you need to explicitly define that this URI corresponds to a variable. The block below defines a new variable named urn:custom:default:variable:emailPass.

{
  "@id": "urn:custom:default:variable:emailPass",
  "@type": "Variable"
}

Parsing the CLI parameter

For this example, we introduce a new CLI parameter emailPass and tell the server to parse it. We do this with the following block:

{
  "@id": "urn:solid-server-app-setup:default:CliExtractor",
  "@type": "YargsCliExtractor",
  "parameters": [
    {
      "@type": "YargsParameter",
      "name": "emailPass",
      "options": {
        "requiresArg": true,
        "type": "string",
        "describe": "The password for the email server."
      }
    }
  ]
}

The options block can contain all values that are defined in the yargs options documentation. The above example tells the CLI parser that the emailPass parameter requires an argument to follow it, and that it needs to be interpreted as a string.

Putting the CLI value into the variable

Once the CLI parameter has been parsed, we need to tell the server which variable to link to that value. Here we can reference the variable we defined above:

{
  "@id": "urn:solid-server-app-setup:default:ShorthandResolver",
  "@type": "CombinedShorthandResolver",
  "resolvers": [
    {
      "CombinedShorthandResolver:_resolvers_key": "urn:custom:default:variable:emailPass",
      "CombinedShorthandResolver:_resolvers_value": {
        "@type": "KeyExtractor",
        "key": "emailPass"
      }
    }
  ]
}

This tells the server to extract the value from the CLI variable emailPass, and put it directly into the variable urn:custom:default:variable:emailPass, thus linking the previous two blocks together.

Using the variable in your configuration

All of the above is to introduce the value of a CLI parameter into the configuration. From this point on, this value can be used anywhere in the configuration. For this part, let's assume that you already have a block in your configuration to define your email account settings. This could, for example, be the block generated by the configuration generator. In that block, you now need to replace the password line, which probably looks something like "emailConfig_auth_pass": "mySecretPassword, with "emailConfig_auth_pass": { "@id": "urn:custom:default:variable:emailPass" }. From then on, when you start the server, the value assigned to the password will be the one provided through the CLI.