Tokens

Tokens

HTML, Mautic, NodeJS and Drupal projects that use the general deployment flow support token replacement.

During deployments, all tokenized strings in the environment's scaffolding data folder are replaced with their actual values sent from Platform.

See ‘general deploy flow’ for more information.

For example, during deploys the tokenized string [[ database_password ]] gets replaced by the actual database password, which is securely stored in Platform.

The following tokens are available to all environments of all projects:

• [[ project_name ]]
  • The machine name of the project, consisting only of alphanumeric characters
• [[ environment_name ]]
  • The machine name of the environment, consisting only of alphanumeric characters
• [[ secret_key ]]
  • A string, unique to this project
• [[ env_secret_key ]]
  • A string, unique to this environment
• [[ proxy_ips ]]
  • A comma-delimited string of our proxy's server IPs, can be used to set up reverse proxy addresses
• [[ unix_timestamp_at_deploy_time ]]
  • The current unix timestamp. As deploys take a snapshot of all tokens, this will for all intents and purposes be the (rough) unix timestamp of the last deploy. Can be used as deployment identifier or as any other string that should be different for each deploy.

The following tokens are available to all environments of project types that support databases (Drupal, Mautic):

• [[ database_user ]]
• [[ database_name ]]
• [[ database_password ]]
• [[ database_port ]]
• [[ database_host ]]

The following tokens are available to all environments of all NodeJS projects:

• [[ nodejs_port ]]
  • This value is uniquely also available as an environment variable, named NODE_PORT

Managing tokens

Platform can define tokens on various "levels", each of which inherit from their "parent" and overwrite any parent tokens.

• The highest level is "global". These tokens are available to all project environments.
• Then we define tokens on a project type basis, which are available to all project environments of that type.
• Next is install profiles.
  • If a specific install profile requires a specific token, we can define it for that install profile and all projects created with that install profile will have access to that token.

    If an install profile is used to set up demo sites, and those demo sites require an API key we can define it as a token for that profile and all sites created with it automatically have access to that token.

The above levels are currently managed solely by Platform administrators. But once a project is created, the user can define more tokens.

• Tokens defined on a project itself make those tokens available to all environments of that project.
• Tokens defined on an environment are available to only that environment.

Each lower level overwrites any tokens that have the same token string from a higher level.

For example, if you wish to use the [[ secret_key ]] token, but give it a specific value for a single environment it is enough to redefine that token on the environment.

That also means you can overwrite the database tokens, but that will not make the database actually use those credentials, so we advise against overwriting those.

When viewing an environment in platform, you will see a "Token" tab. There you will see a "custom tokens" and "computed tokens" tab. The computed tokens tab will show you all tokens that are available to that environment, including global, type, profile and project tokens. The custom tokens tab is where you can enter your own tokens.

You can also define tokens on the project level, by visiting the Token tab on the project detail page.

Structure of tokens

All predefined tokens use the following structure: [[ alphanumeric_and_underscores_lowercase_string ]] but there is no hard rule that that must be the case. We chose that structure so as not to conflict with legitimate strings inside the scaffolding folders. When creating your own tokens, you are free to use any string you want.

How to handle sensitive data

Tokens often times will contain sensitive data, such as API keys. If that is the case, you can mark the token as containing sensitive data. Platform will then encrypt the data before saving, and it will only be decrypted right before being replaced during the scaffolding phase of any deployment or when editing that token.

In that case, when viewing the token outside the editing UI you will only see the encrypted string.

Where to use tokens

Tokens only get replaced during deployments, and only in files inside the scaffolding folder for the environment being deployed. So when deploying a dev environment, all tokens inside any files inside the .dropsolid/scaffold/dev folder will get replaced with the actual values right before being scaffolded into their deployed location.

The future

In the future, we want to support environment variables. Either instead of tokens, or alongside tokens. Regardless of what gets decided, you will be able to manage those environment variables much like you can manage tokens today.