WIP

source/content/guides/secrets/01-introduction.md

@@ -2,9 +2,7 @@
 title: Pantheon Secrets Guide
 subtitle: Introduction
 description: Securely store secrets in the Pantheon Platform.
-terminuspage: true
 type: terminuspage
-layout: terminuspage
 contributors: [stovak]
 contenttype: [guide]
 innav: [true]

source/content/guides/secrets/02-basic-concepts.md

@@ -2,9 +2,6 @@
 title: Pantheon Secrets Guide
 subtitle: Basic Concepts
 description: This section outlines some concepts that are worth knowing about Pantheon Secrets. Gaining familiarity with them will help you to make better use of this feature.
-terminuspage: true
-type: terminuspage
-layout: terminuspage
 contributors: [stovak]
 contenttype: [guide]
 innav: [true]
@@ -19,7 +16,8 @@ reviewed: "2024-05-01"
 ---
 <dl>  
 <dt>Secret</dt>
-<dd>A key-value pair that should not be exposed to the general public, typically something like a password, API key, or other sensitive information that you should probably not add to version control.</dd>
+<dd>
+A key-value pair that should not be exposed to the general public, typically something like a password, API key, or other sensitive information that you should probably not add to version control.</dd>
 
 <dt>Secret type [^1]</dt>
 <dd>

source/content/guides/secrets/03-terminus-plugin.md

@@ -2,9 +2,6 @@
 title: Pantheon Secrets Guide
 subtitle: Terminus Secrets Manager Plugin
 description: Terminus plugin for Pantheon Secrets
-terminuspage: true
-type: terminuspage
-layout: terminuspage
 contributors: [stovak]
 contenttype: [guide]
 innav: [true]

source/content/guides/secrets/04-use-cases.md

@@ -3,8 +3,6 @@ title: Pantheon Secrets Guide
 subtitle: Use Cases
 description: Some common uses cases for Pantheon Secrets
 terminuspage: true
-type: terminuspage
-layout: terminuspage
 contributors: [stovak]
 contenttype: [guide]
 innav: [true]
@@ -36,9 +34,74 @@ TEST THAT WHAT IS IN THE PLUGIN STILL WORKS!
 
 # Use Case: Using secrets with Drupal Key module
 
-[https://github.com/pantheon-systems/pantheon_secrets/blob/1.0.x/docs/example.md](https://github.com/pantheon-systems/pantheon_secrets/blob/1.0.x/docs/example.md)
+# Pantheon Secrets detailed example
 
-Also short version in README: [https://github.com/pantheon-systems/pantheon_secrets/blob/1.0.x/README.md#usage](https://github.com/pantheon-systems/pantheon_secrets/blob/1.0.x/README.md#usage)
+Please look at the [module documentation](../README.md) if you have not done so yet.
+
+In this guide we will go over an end to end example on how to setup secrets for a given site and how to use those secrets on a module that integrates with the Key module. For this example, we will use the [Sendgrid API](https://www.drupal.org/project/sendgrid_api) and [Sendgrid Mailer](https://www.drupal.org/project/sendgrid_mailer) modules.
+
+## Prerequisites
+
+1) Make sure you have access to a Drupal >= 9.4 site running PHP >= 8.0 hosted on Pantheon.
+
+1) Make sure you have [terminus installed](https://docs.pantheon.io/terminus/install#install-terminus) in your machine
+
+1) Install the [Secrets Manager Plugin](https://github.com/pantheon-systems/terminus-secrets-manager-plugin#installation)
+
+1) Install the required modules in your Drupal site and push the changes to Pantheon:
+    ```
+    composer require drupal/pantheon_secrets drupal/sendgrid_api drupal/sendgrid_mailer
+    git add composer.json composer.lock
+    git commit -m "Add required modules."
+    git push
+    ```
+
+1) Enable the modules:
+    ```
+    terminus drush <site>.<env> -- en -y pantheon_secrets sendgrid_api sendgrid_mailer
+    ```
+
+1) Make sure your Sendgrid account is correctly configured and allows sending email.
+
+1) Create a Sendgrid API key by following [Sendgrid instructions](https://docs.sendgrid.com/ui/account-and-settings/api-keys#creating-an-api-key)
+
+1) Store the API key as a site secret:
+    ```
+    terminus secret:site:set <site> sendgrid_api <api_key> --scope=web --type=runtime
+    ```
+
+    You can optionally add a [secret environment override](https://github.com/pantheon-systems/terminus-secrets-manager-plugin#environment-override) to change the API key for a given environment (e.g. you want to use different Sendgrid accounts for live and dev environments)
+
+1) Add the Key entity in one of the different available ways:
+
+    1) Add a new key through the Key module UI. Select Pantheon Secret as the key provider and your secret name from the dropdown (make sure you select "Sendgrid" as the Key type and "Pantheon" as the Key provider)
+
+        ![Screenshot of creating a new Key entity with type "Sendgrid" and provider "Pantheon"](add-key.png)
+
+    1) Go to /admin/config/system/keys/pantheon and click on the "Sync Keys" button to get all of the available secrets into Key entities.
+
+        ![Screenshot of Sync Pantheon Secrets page in Drupal UI](../../../images/sync-keys.png)
+
+        Then, edit the sendgrid_api Key and change the type to "Sendgrid"
+
+    1) Use the provided drush command to sync all of your secrets into Key entities:
+        ```
+        terminus drush <site>.<env> -- pantheon-secrets:sync
+        ```
+
+        Then, edit the sendgrid_api Key and change the type to "Sendgrid"
+
+1) Go to the Sendgrid API Configuration page (/admin/config/services/sendgrid) and select your Key item
+
+    ![Screenshot of Sendgrid API Configuration page in Drupal UI](../../../images/sendgrid-config.png)
+
+1) Make sure your site "Email Address" (/admin/config/system/site-information) matches a verified Sender Identity in Sendgrid
+
+1) Go to the Sendgrid email test page (/admin/config/services/sendgrid/test) and test your Sendgrid integration by sending a test email
+
+    ![Screenshot of Sendgrid email test page in Drupal UI](../../../images/sendgrid-email-test.png)
+
+1) The email should get to your inbox. Enjoy!
 
 # Use Case: Accessing secrets from your codebase
 

source/content/guides/secrets/05-local-development.md

@@ -1,10 +1,8 @@
 ---
 title: Pantheon Secrets Guide
-subtitle: Terminus Secrets Manager Plugin
-description: Securely store secrets in the Pantheon Platform.
+subtitle: Local development using Pantheon Secrets
+description: Developing locally presents some unique challenges once Pantheon Secrets are built into your workflow. These are some tips to help you get past struggling with trying to reproduced secret behavior while developing locally.
 terminuspage: true
-type: terminuspage
-layout: terminuspage
 contributors: [stovak]
 contenttype: [guide]
 innav: [true]
@@ -17,10 +15,56 @@ tags: [reference, cli, local, terminus, workflow]
 permalink: docs/guides/secrets/local-development
 reviewed: "2024-05-01"
 ---
-# Pantheon Secrets and local development environments
+## Local Environment Usage
 
-## Introduction
+The SDK includes a `CustomerSecretsFakeClient` implementation that is used when the SDK runs outside of Pantheon infrastructure. This client uses a secrets json file to build the secrets information emulating what happens on the platform using the Secrets service.
 
-Your local dev env won't ever be able to talk directly to secrets service so you need workarounds!! (THIS IS NOT REAL DOCS TEXT)
+To get this file, you should use the [plugin](https://github.com/pantheon-systems/terminus-secrets-manager-plugin/) `secret:site:local-generate` command and then set an environment variable into your local environment (or docker container if you are running a docker-ized environment) with name `CUSTOMER_SECRETS_FAKE_FILE` and use the absolute path to the file as the value.
 
-Document this: [https://github.com/pantheon-systems/customer-secrets-php-sdk?tab=readme-ov-file#local-environment-usage](https://github.com/pantheon-systems/customer-secrets-php-sdk?tab=readme-ov-file#local-environment-usage)**
+
+### LANDO example
+
+1. To setup this using lando, you should modify your `.lando.yml` like this:
+    ```yaml
+    services:
+      appserver:
+        overrides:
+          environment:
+              CUSTOMER_SECRETS_FAKE_FILE: /app/secrets.json
+    ```
+    
+2. Generate the secrets file like this:    
+    ```bash
+    terminus secret:site:local-generate --filepath=./secrets.json
+    ```
+
+3. And rebuild lando application:
+    ```bash
+    lando rebuild -y
+    ```
+
+Now, you will be able to use your secrets through the SDK.
+
+
+### DDEV example
+
+1. CD to your ddev root directory.
+
+2. To setup using DDEV, add the following to your `~/.ddev/config.yml`
+    ```yaml
+    web_environment:
+    - CUSTOMER_SECRETS_FAKE_FILE=./secrets.json
+    ```
+
+3. Generate the secrets file
+    ```bash
+    terminus secret:site:local-generate --filepath=./secrets.json
+    ```
+
+4. Restart your ddev environment
+    ```bash
+    ddev restart
+    ```
+
+## Restrictions
+This SDK will only read secrets with scope `web`. Secrets get cached in the server for 15 minutes so you should wait (at most) that time if you modified your site secrets.

source/content/guides/secrets/06-troubleshooting.md

@@ -3,8 +3,6 @@ title: Pantheon Secrets Guide
 subtitle: Terminus Secrets Manager Plugin
 description: Securely store secrets in the Pantheon Platform.
 terminuspage: true
-type: terminuspage
-layout: terminuspage
 contributors: [stovak]
 contenttype: [guide]
 innav: [true]
@@ -21,9 +19,74 @@ reviewed: "2024-05-01"
 
 ## Integrated Composer Build fails on private packages
 
-Start with [https://getpantheon.atlassian.net/wiki/spaces/CS/pages/2703294468/IC+Build+fails+on+private+packages](https://getpantheon.atlassian.net/wiki/spaces/CS/pages/2703294468/IC+Build+fails+on+private+packages) and make it user friendly
+This is the most common error when sites are using secrets and Integrated Composer. This may manifest in different ways and may be caused by different problems. This playbook tries to cover them.
 
-## Errors setting or deleting secrets
+**Error getting a private package during the IC build**
+
+This is the most common error; an example message associated to this error is:
+
+- Failed to download vendor/package from dist (where vendor/package may be any private package)
+
+Some possible causes for this error:
+
+<dl>
+<dt>
+**Problem:** Secrets are not correctly set for the site. Secrets for IC should be of scope ic and type composer. See instructions in the plugin README: [https://github.com/pantheon-systems/terminus-secrets-manager-plugin#mechanism-1-oauth-composer-authentication](https://github.com/pantheon-systems/terminus-secrets-manager-plugin#mechanism-1-oauth-composer-authentication)
+</dt>
+<dd>
+**Solution:** ask the client to delete and recreate the secret if scope and type do not match for the given secret name
+</dd>
+</dl>
+
+<dt>
+**Problem:** Secret value/token may be expired
+</dt>
+<dd>
+**Solution:** ask the client to set the secret again to an updated value
+</dd>
+
+<dt>
+Problem: Site may be running on a PHP version < 8. If this is the case, there will be a message in the job output: “Skipping setting up secrets as it is not supported in PHP < 8”
+</dt>
+<dd>
+Solution: ask the client to upgrade to PHP 8.1 or greater
+</dd>
+
+<dt>
+**Problem:** Errors with paid WordPress plugins. 
+
+Example error message associated to this:
+
+- Could not find a license key for ACF PRO. No valid license key could be found
+
+Possible causes for this error:
+
+- This error happens when [https://packagist.org/packages/pivvenit/acf-pro-installer](https://packagist.org/packages/pivvenit/acf-pro-installer) is used and the ACF_PRO_KEY is not available
+- Please note that the plugin is no longer supported by the developer as ACF now has built-in composer support. It’s a good idea to recommend customers to switch to it.
+</dt>
+<dd>
+**Solution:** 
+
+If the plugin is still in use:
+- Look for the secret with name ACF_PRO_KEY, it should be of type env and scope ic. Delete and recreate if type or scope doesn’t match.
+
+- Make sure the site is running PHP >= 8
+
+</dd>
+<dt>
+**Problem:** Error cloning private package via SSH. IC builds + secrets management is intended to clone over https and not over ssh as that would require a ssh key and the process to set things up is way more complex than http auth.
+
+An example error message associated to this error is:
+
+- Failed to execute git clone --mirror -- 'git@github.com:biltmoreco/advanced-custom-fields-pro.git' '/home/pantheon-app/.cache/composer/vcs/git-github.com-biltmoreco-advanced-custom-fields-pro.git/'
+
+</dt>
+<dd>
+**Solution:** Change the repository definition (in composer.json) to use https instead of ssh. In this example, the repository would be https://github.com/biltmoreco/advanced-custom-fields-pro.git
+</dd>
+<dt>
+**Problem:** Errors setting or deleting secrets
+</dt>
 
 [https://getpantheon.atlassian.net/wiki/spaces/CS/pages/2703163413/Errors+setting+or+deleting+secrets](https://getpantheon.atlassian.net/wiki/spaces/CS/pages/2703163413/Errors+setting+or+deleting+secrets)