Installation

To install Precomposer, the following steps need to be taken:

1. Create a copy of the Precomposer start template repository
2. Configuration
3. Start the GitHub workflow
4. Register DNS names

1. Copying the Precomposer-Template-Repository

1. Navigate to the repository: epc-deployment-configurations (opens in a new tab).

2. Create a new repository using the template:

   • Click the "Use this template" button (located at the top right, above the code).
   • Select "Create a new Repository".

3. Choose a name and location for your new deployment repository:

   • You can freely decide the name and location.

   Important: If you choose a name other than epc-deployment-configurations, you must update the service repositories (e.g., storefront) to reflect the new name. This ensures that the services' build pipelines can locate and trigger your deployment repository correctly.

4. After the successful creation the next steps will be done in your own copy.

2. Configuration

To set up your newly created repository with GitHub Action variables and secrets. This is how you can add secrets and variables to your repository:

1. Navigate to: Settings -> Secrets and Variables -> Actions.

2. To create a GitHub Action Secret:

   • Switch to the "Secrets" tab.
   • Click the green button "New repository secret".

3. To create a GitHub Action Variable:

   • Switch to the "Variables" tab.
   • Click the green button "New repository variable".

Configuration for Cluster/Provider Access

Add the following as GitHub Action Secrets:

Details about PERSONAL_ACCESS_TOKEN

How to create it:

1. Go to GitHub -> Profile photo -> Settings -> Developer settings -> Personal access tokens -> Generate new token.
2. Follow the instructions to generate a new token. More information can be found here (opens in a new tab).
3. Ensure the token is created by the same user who has access to the newly copied Precomposer-Template-Repository.

Required permission scopes:

• repo: For repository access.
• write:packages: For registry access.

Where it is used:

1. Deploys a generated SSH key in your deployment-configurations repository, allowing ArgoCD to access it.
2. Creates a docker-pull-secrets secret in the Kubernetes cluster, enabling the cluster to fetch container images.

Details about K8S_CLUSTER_CONFIG

What it is:

• The Kubernetes cluster configuration file (commonly used as $KUBECONFIG in the shell).

How to retrieve it:

• Run the following command to generate a minimal configuration:

kubectl config view --minify --flatten

For DigitalOcean clusters:

1. Go to the cluster's overview page.
2. Switch to the "Settings" tab.
3. Click the blue "Actions" button (top right) and select "Download Config".

How to use it:

• Copy the entire content of the configuration file and paste it into the secret field when creating this GitHub Action Secret.

Details about DO_ACCESS_TOKEN

What it is:

• A token required for DigitalOcean clusters to determine the cluster's external IP address.

How to create it:

1. Go to DigitalOcean -> API (main navigation left side) -> Generate New Token.
2. Click the "Generate New Token" button (top right).
3. Select both read and write scopes. More information can be found here (opens in a new tab).

Configuration of the Services

To configure the composable commerce services (e.g., Commercetools, Storyblok), you need to add the required secrets as GitHub Action Secrets. Follow the instructions below for each service and refer to the detailed explanations for additional context.

Adding Secrets

These secrets are prefixed with TO_K8S_ to indicate they are written directly to your Kubernetes cluster and are no longer relevant in GitHub after deployment.

You can add these secrets either:

• Manually via the GitHub UI: Navigate to Settings -> Secrets and Variables -> Actions.
• Using GitHub CLI: If you're familiar with the GitHub CLI, use the github-secrets-example.txt file in the root of your new repository. This file contains all required secrets and an example command to populate them into a GitHub repository.

Required GitHub Action Secrets

• * Required when Algolia is used as the search provider for products.
• ** Required when the Commercetools Checkout solution is used.

Details About the Secrets

Commercetools Credentials

Why Two API Clients? (TO_K8S_COMMERCETOOLS_AUTH_CLIENT_ID, TO_K8S_COMMERCETOOLS_CLIENT_ID)

• Auth API Client: Used for session-related tokens after user login. These tokens are scoped to view personal entities (e.g., carts, orders). When creating this client use the Mobile & single-page application client template.
• General API Client: Used for standard shop requests (e.g., product search, anonymous checkout). When creating this client use the Admin client template.

How to Create API Clients

1. Go to Commercetools -> Settings -> Developer Settings.
2. Click "+ Create new API client".
3. Configure the clients as per the required scopes.

Algolia Credentials

• ALGOLIA_APPLICATION_ID: Found in the Algolia Dashboard under the Search tab (top left).
• ALGOLIA_SEARCH_KEY: A read-only API key for enabling search capabilities. Found in Dashboard -> Settings -> API Keys.

SendGrid Credentials

• SENDGRID_API_KEY: Full-access API key from your SendGrid account. Required for the epc-email-processor to interact with SendGrid templates.

Storyblok Credentials

• STORYBLOK_MGMT_TOKEN: Management token only necessary for importing demo data. Generate it via Storyblok -> My Account -> Account Settings -> Personal Access Token.
• STORYBLOK_SPACE_ID: Space ID for importing data. If missing, a default space is created (not recommended due to rate limits).
• TO_K8S_STORYBLOK_ACCESS_TOKEN: Access token for read-only operations. Generate it via Storyblok Space -> Settings -> Access Tokens.

Additional GitHub Action Variables

Notes on Specific Variables

• TO_K8S_COMMERCETOOLS_PROJECT_KEY: Found in Commercetools -> My Account -> Manage Projects.
• TO_K8S_SEARCH_PROVIDER_TO_USE: Specifies the search provider (algolia or commercetools). Defaults to commercetools if unset.
• TO_K8S_CHECKOUT_TYPE: Specifies the checkout type (precomposer or commercetools). Defaults to precomposer if unset.
• TO_K8S_SENDER_EMAIL_ADDRESS: Must be a verified sender email in SendGrid.

Final Notes

• Ensure all the above secrets and variables are set at this point.
• For more details on configuring specific services, refer to their respective documentation.

3. Start the GitHub Workflow

From your repository, start the workflow "Install Precomposer on k8s cluster":

You can do this via Main menu of the project -> Actions -> (if necessary) close the GitHub introduction dialogue -> Install Precomposer on k8s cluster.

Input Parameters

The workflow accepts the following input parameters:

(How the DNS names are composed of the specified variable values is explained in the next section).

Workflow Run

After submitting the parameters, GitHub will start the workflow. A new "workflow run" will appear after a few seconds.

1. To monitor progress: Go to Actions -> Workflow Runs -> Click on the latest run.

2. To view details: Go to Workflow Summary -> Click on individual jobs.

Notes

• The execution typically takes a few minutes. However, some steps (e.g., waiting for services to start or registering DNS names) may take longer.
• Ensure all input parameters are correctly configured before starting the workflow.

4. Register DNS Names

The DNS names must be registered in your DNS system.

• If you specified precomposer.shop as the base domain: This step is not necessary. The DNS names will be registered for you automatically.

• If you are using your own domain: You must manually set up the DNS names to point to the external IP (e.g., load balancer) of the Precomposer setup.

Finding the External IP

1. Locate the external IP:

   You can get the IP via Actions -> Workflow Runs -> !!! MANUAL ACTION HERE: Getting started -> Step: !!! MANUAL ACTION HERE: Getting started.

   • If the setup process successfully detects the external IP, it will be displayed in this step.
   • If the external IP is not displayed, you will need to determine it manually using your cluster provider's tools.
   

Setting Up DNS Names

Once you have the external IP, you can (and should) set up the DNS names manually while the setup workflow is still running.

Note: DNS propagation and Let's Encrypt certificate registration can take time, so starting this process early is recommended.

• Ensure all DNS names point to the same external IP of your cluster (load balancer).

DNS Name Composition

The DNS names are composed as follows:

Example

For the following input parameters:

• DNS_BASE_DOMAIN: precomposer.shop
• DNS_DOMAIN_PREFIX: demo
• PROJECT_ENVIRONMENT: test

The resulting DNS names would be:

Notes

• If you are not using precomposer.shop, ensure the DNS names are set up correctly and point to the external IP before the workflow completes.
• Use your cluster provider's tools to verify the external IP if it is not automatically detected.