Secrets

Short explaination

Secrets are mostly data to access something. A simple example could be the login data to a docker registry or tokens to download private composer packages. With this implementation it allows us to define secrets in a central location. So when you setup a project, you don´t need to copy your auth.json or docker login data into your project, WebDev will take care of it.

Defining Secrets

Secrets are being defined in the webdev.yaml file of your project and might look like this

secrets:
  ComposerSecret:
    source:
      key: auth
      group: composer
    target:
      file: auth.json
  GitlabDockerLoginSecret:
    source:
      key: gitlab_docker_login
      group: docker
    target:
      envVar: file

In this we define two secrets named ComposerSecret and GitlabDockerLoginSecret. The first one defines a auth.json file that is used to access private compose packages. With the other one we define login data for the docker registry.

Source

The source defines the key and the group of the secret we want to fetch. Depending from where the secrets are being fetched, these will have different meaning. So look at the SourceHandler Section to get more informations about it.

Target

Once we fetched the secrets from the source, the target defines on how to handle that secrets.

File

When we set the file property, then WebDev knows that we want to save it to a file. In this example we write the content of the secret to auth.json. The file name is relativ to the project root and can contain of course also folders. So the value project/src/auth.json is possible too.

envVar

The set value is not relevant as the secret itself defines the name and value of the variable. So the secret should be formatted this way:

DOCKER_USER=user
DOCKER_PASSWORD=test234

So WebDev will read each line of the secret and check if it defines a environment variable. These can then be used for example within your tasks, so that he login to the docker registry, before trying to pull the service images.

SourceHandler

Currently only one SourceHandler has been implemented but in the future more might be added.

Filesystem SourceHandler

This handler loads all secrets from your local filesystem. While it requires that every developer sets their own secrets up for himself, it is the easiest to implement and doesn´t require any central service like a Vault server.

WebDev will check if the secret exists as file within the path ~/webdev/secrets. The key is the name of the file without any extensions and the group defines the subfolder, if it defined. So in the first case ComposerSecret the file should be located under the path ~/webdev/secrets/composer/auth.json. As said before, the file extension is not relevant, so the file could also be named auth.txt.

Give better feedback to the user Since v0.3.2

When a secret was missing, webdev was just saying that a secret could not be found. This wasn´t very helpful for a user to find out what secret was missing or how he can add it. That´s why the missingMessage Attribute has beend added. Now a more detailed explaination can be added for the user, giving him instructions on how to find the neccessary data and how to add it.

secrets:
  ComposerSecret:
    missingMessage: Secrets.Missing.Composer
    source:
      key: auth
      group: composer
    target:
      file: auth.json
      expectedSecrets:
        - GitLab
        - Package Repository

First we define a missing message with the value Secrets.Missing.Composer. The text for this can be found in the ~/webdev/translations/en.yml file or here. As you can see it gives the user way better feedback on what todo. You may also notice there are some placeholders #SECRET_FILE_NAME#, #SECRET_FILE_DIRECTORY# and #COMPOSER_AUTH_SECRETS#. The first two will be generated by webdev depending on the values you have defined for that secret. The third one is based on the values you have set under expectedSecrets. It will just combine the given values and outputs them.

Another example:

GitlabDockerLoginSecret:
    missingMessage: Secrets.Missing.DockerLogin.Gitlab
    source:
      key: gitlab_docker_login
      group: docker
    target:
      envVar: file
      expectedVars:
        - DOCKER_USERNAME
        - DOCKER_PASSWORD

It works the same way as the example above but now for Environment variables. The main difference is, that webdev can check if the variables have been defined in that file. If one or more is missing, he will outputs an error message, telling you which of the variables are not set.

Adding your own error messages Since v0.3.2

In some cases you want to add your own messages, either because no matching error message is available or you need to customize the message to further clarify for the user what he needs to do. As said above, the error messages are loaded from the file ~/webdev/translations/en.yml but changing this file to add your own messages would not be good idea since all updates of the tool will overwrite them.

Order on which translation files will be loaded:

• ~/webdev/translations
• ~/.webdev/translations
• PROJECT_FOLDER/.webdev/translations

Placing a translation file into the second folder, would be advised when you want to add general translations. The third folder is the one for project specific translations.