Injecting Commerce Configuration at Startup

Overview

Self Managed Commerce container images support injecting commerce configuration from a separate, encrypted Git repository during container startup. This allows you to do the following:

Keep production and other sensitive secrects secured in a separate Git project, so you do not need to check them into your Self Managed Commerce ep-commerce project.
Override configuration set in the Self Managed Commerce ep-commerce project.

This method of injecting configuration is secured using Git repositories, Gnu Privacy Guard (GPG) keys and git-crypt.

Note: You must be familiar with Self Managed Commerce configuration in the deployment package. For more information about the configuration in the deployment package, see Self Managed Commerce Configuration. For more information about environment configuration, see Environment Specific Configuration.

Using a Secure Configuration Repository

A secure configuration repository is a Git repository that you create separate from your other Git repositories. You must create a secure configuration repository to store secrets that you want to store separately from your Self Managed Commerce ep-commerce Git repository.

A secure configuration repository can be used with one of more of the Self Managed Commerce stacks. You can configure a stack to use the secure configuration repository by setting specific environment variables, as described in this document.

note

If you configure the Self Managed Commerce containers to use a secure configuration repository then the following will be true:

The Self Managed Commerce containers configured to use the secure configuration repository will and have access to all of the files and secrets stored in the secure configuration repository.
The files and secrets from the secure configuration repository will remain on the container filesystems for the life of the containers.

Preparing a Secure Configuration Repository

Additional setup is required to use this functionality, including the following tasks:

Creating a new Git repository containing configuration that will be injected
Creating a new Secure Shell (SSH) key that is used for cloning the repository
Creating a new GPG key that is used for encrypting the repository
Encrypting the Git repository using git-crypt
Noting the public host key of the server hosting the new Git repository

Pre-requisites

Ensure that you install the following tools on your local workstation:
- Git
- GPG
- git-crypt

Creating the Git repository

Create a new Git repository

Note: If you can use the same Git repository hosting service that you use to host the CloudOps for Kubernetes repositories.
Create a new SSH key-pair. Authorize the key-pair under a utility account to clone the newly created repository. Save both the privvate and public keys.

Note: Password protected SSH keys are not supported.

Encrypting the repository

Clone the Git repository that you created in the Creating the Git repository section.
Run the following command to initialize the repository with git-crypt:
```
git-crypt init
```
Create a .gitattributes file in the repository with the following contents:
```
* filter=git-crypt diff=git-crypt
.gitattributes !filter !diff
```
Note: This Git attributes file will configure git-crypt to encrypt everything in the repository. To configure git-crypt differently, see the git-crypt documentation.
Add and commit the .gitattributes file.
Run the following command to create a new GPG key pair:
```
gpg --gen-key
```
Note: Password protected GPG keys are not supported. Additionally, we recommend using a long-term utility account email instead of a personal email.
Run the following command to authorize the GPG key to unlock the repository:
```
git-crypt add-gpg-user $ID
```
Note: Replace $ID with the ID of the GPG key from step 5.
Run the following command to export the private GPG key to a local unencrypted directory:
```
gpg --export-secret-keys -a $ID > /path/to/unencrypted/directory/my-private-key.asc
```
Note: Replace $ID with the ID of the GPG key from step 5

Now you can commit and push the configuration files and secrets to the repository as needed.

Adding Self Managed Commerce Configuration

Add Self Managed Commerce configuration to the repository in the same format as Commerce configuration in the deployment package.

Note: For the configuration to be copied during the deployment, ensure that your environment folder follows this directory format.

${env-name}
   files
      ...
   ...

You can include multiple configuration sets in the repository. The following example is a production configuration containing certificates and other secret information:

prod-author
   files
      conf
         secure
            author-certificate-1.p12
            author-certificate-2.p12
   secure-filtering.properties

prod-live
   files
      conf
         secure
            live-certificate-1.p12
            live-certificate-2.p12
   secure-filtering.properties

Add and commit the configuration files.

Run git-crypt status to validate the files are encrypted correctly.

The output of the command will look similar to the following example:

$ git-crypt status
not encrypted: .git-crypt/.gitattributes
not encrypted: .git-crypt/keys/default/0/6E34CFEF60D34EAD74735515634491886294C9C3.gpg
not encrypted: .gitattributes
    encrypted: prod-author/files/conf/ep.properties
    encrypted: prod-author/filtering.properties
    encrypted: prod-live/data-population.properties
    encrypted: prod-live/files/conf/cache/ehcache-2-seconds.xml
    encrypted: prod-live/files/conf/cortex/jwtTokenStrategy.config
    encrypted: prod-live/files/conf/ep.properties
    encrypted: prod-live/filtering.properties

Creating the GPG and SSH Key Secrets

Copy the contents of the private GPG key created in the Encrypting the repository section.

The contents will start and end with the following lines:
```
----BEGIN PGP PRIVATE KEY BLOCK-----

<redacted>

-----END PGP PRIVATE KEY BLOCK-----
```
Add the GPG key to your CI/CD tooling. It will need to be passed to the containers using environment variable EP_COMMERCE_CONFIG_GPG_KEY.
Repeat steps 1 to 2 with the SSH private key created in the Creating the Git repository section. The SSH private key will need to be passed to the containers using environment variable EP_COMMERCE_CONFIG_SSH_KEY.

Finding the public host key

Identify the hostname of the Git repository hosting service that you are using.

Some common hosting services include:
- github.elasticpath.net
- github.com
- gitlab.com
- bitbucket.org

Run ssh-keyscan to fetch the public host key of the server.

$ ssh-keyscan github.com 2> /dev/null
github.com ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ==

Run the following command to generate the public fingerprint using the public key featched using ssh-keyscan

$ ssh-keyscan github.com 2> /dev/null | ssh-keygen -lf -
2048 SHA256:nThbg6kXUpJWGl7E1IGOCspRomTxdCARLviKw6E5SY8 github.com (RSA)

Compare the fingerprint with the Git hosting service documentation to validate that you have the correct public host key.

The following documentation links are for common hosting services containing fingerprints:
- Github
- Gitlab
- Bitbucket

The public host key will need to be passed to the containers using environment vaiable EP_COMMERCE_CONFIG_HOST_KEY.

Configure the Containers with Environment Variable

Set the below environment variables in the Commerce application containers to have them use the secure configuration repository.

`EP_COMMERCE_CONFIG_REPO`

This is the SSH URL to the secure configuration Git repository.

`EP_COMMERCE_CONFIG_GPG_KEY`

This is the GPG SSH key credential that you created in the Creating the GPG and SSH Key Secrets section.

`EP_COMMERCE_CONFIG_SSH_KEY`

This is the Git SSH key credential that you created in the Creating the GPG and SSH Key Secrets section.

`EP_COMMERCE_CONFIG_HOST_KEY`

This is the host key that you validated in the Finding the public host key section.

Configuration Source Priority

note

Both the Self Managed Commerce ep-commerce repository and the secure configuration repository may contain configuration files that apply to multiple Commerce environments, with some files possibly being specific to one environment. The containers use the environment variable EP_COMMERCE_ENVNAME to determine which files to apply. The EP_COMMERCE_ENVNAME environment variable indicates which fileset to use when loading configuration at start-up time, and corresponds to folders in the Git repositories under extensions/database/ext-data/src/main/resources/environments. Your Commerce development team can confirm which value to use for a given environment.

Be aware of the order in which configuration files arr consumed from ep-commerce repository and the secure configuration repository. Understanding this helps to ensure that configuration for an environment is constructed correctly.

Files are copied from the default configuration folder in the Self Managed Commerce ep-commerce repository.
Files are copied from the environment folder, specified by EP_COMMERCE_ENVNAME, in the Elastic Path Commerce ep-commerce repository if that folder existis
Files are copied from an environment folder, specified by EP_COMMERCE_ENVNAME, in the secure configuration repository if that folder existis.