Docs and website update (#515)

* docs(README.md): add GitHub Docs section with links to detailed documentation for various components of Signatory to improve project understanding and usability * docs(README.md): restructure documentation links for better readability feat(docs): add new documentation for AWS DynamoDB watermark backend to provide guidance on its configuration and usage * style(sidebars.js): reformat the items array for better readability feat(sidebars.js): add new items 'aws_dynamodb', 'pkcs11' to the docs sidebar for additional documentation coverage * feat(sidebars.js): add new categories for Watermark Backends and Vault Backends to improve documentation navigation * refactor(sidebars.js): reorganize sidebar items into categories for better readability feat(sidebars.js): add 'collapsed: false' to categories to have them expanded by default for easier navigation * docs: update PKCS#11 documentation to include AWS CloudHSM compatibility - Update README.md and pkcs11.md to reflect AWS CloudHSM compatibility in the PKCS#11 section - Add a note in pkcs11.md about AWS CloudHSM backend setup requirements - Change the formatting of notes in pkcs11.md for better readability * style(sidebars.js): improve code readability by fixing indentation and line breaks in the sidebar categories feat(sidebars.js): add 'collapsed: false' to 'Client Authorization' category to make it expanded by default
ecadlabs · Jan 24, 2025 · c6c24b0 · c6c24b0
1 parent 4aee6f9
commit c6c24b0
Show file tree

Hide file tree

Showing 4 changed files with 118 additions and 30 deletions.
diff --git a/README.md b/README.md
@@ -24,6 +24,34 @@ Security and convenience are typically at odds with each other. Signatory makes
 
 ---
 
+## GitHub Docs
+
+Explore detailed documentation for various components of Signatory:
+
+### Introduction
+- [Getting Started](./docs/start.md)
+- [Authorized Keys](./docs/authorized_keys.md)
+- [Command-Line Interface (CLI)](./docs/cli.md)
+- [Bakers](./docs/bakers.md)
+
+### Vault Backends
+- [Azure KMS](./docs/azure_kms.md)
+- [AWS KMS](./docs/aws_kms.md)
+- [Google Cloud KMS](./docs/gcp_kms.md)
+- [Hashicorp Vault](./docs/hashicorp_vault.md)
+- [Ledger Integration](./docs/ledger.md)
+- [Local Secret Storage](./docs/localsecret.md)
+- [PKCS#11 (AWS CloudHSM compatible)](./docs/pkcs11.md)
+- [YubiHSM](./docs/yubihsm.md)
+
+### Watermark backends 
+- [AWS (DynamoDB)](./docs/aws_dynamodb.md)
+
+### Other
+- [JWT Authentication](./docs/jwt_auth.md)
+- [Remote Policy Configuration](./docs/remote_policy.md)
+- [Signatory Architecture](./docs/signatory-architecture.md)
+
 ## Features
 
 ### Remote Signing

diff --git a/docs/aws_dynamodb.md b/docs/aws_dynamodb.md
@@ -0,0 +1,41 @@
+---
+id: aws_dynamodb
+title: AWS Watermark Backend
+---
+
+# AWS DynamoDB Watermark Backend Configuration
+
+Signatory supports using AWS DynamoDB for watermark tracking. This allows for reliable and scalable management of watermarks in distributed environments.
+
+## AWS DynamoDB Watermark Backend
+
+Below is the minimum configuration required:
+
+```yaml
+watermark:
+  driver: aws
+  config:
+    access_key_id: <aws_access_key_id>
+    secret_access_key: <aws_secret_access_key>
+    region: <aws_region>
+```
+When the backend is initialized, it will create a table named `watermark` if it doesn't exist.
+
+### Configuration Parameters
+
+| Name              | Type   | Required | Description                                                         |
+|-------------------|--------|:--------:|---------------------------------------------------------------------|
+| access_key_id     | string | OPTIONAL | IAM user detail for accessing DynamoDB                              |
+| secret_access_key | string | OPTIONAL | IAM user detail for accessing DynamoDB                              |
+| region            | string | ✅       | AWS region where the DynamoDB table is located                      |
+| table             | string | OPTIONAL | Name of the DynamoDB table to use for watermark tracking (default: `watermark`) |
+
+### Environment Variables Support
+
+The `access_key_id`, `secret_access_key`, and `region` fields can also be set using the following environment variables:
+
+- `AWS_ACCESS_KEY_ID`
+- `AWS_SECRET_ACCESS_KEY`
+- `AWS_REGION`
+
+The `table` parameter defaults to `watermark` but can be overridden in the configuration file.
diff --git a/docs/pkcs11.md b/docs/pkcs11.md
@@ -1,10 +1,12 @@
 ---
 id: pkcs11
-title: PKCS#11
+title: PKCS#11 (AWS CloudHSM compatible)
 ---
 
 # PKCS#11 Vault
 
+> **Note**: The PKCS#11 configuration is commonly used for signing with an AWS Cloud HSM backend. Ensure that your AWS Cloud HSM setup is properly configured and the required libraries are available.
+
 ## Configuration
 
 | Field                      | Type                               | Required | Description                                                  |
@@ -24,7 +26,7 @@ title: PKCS#11
 | public_value     | Base58 string            |          | Public key value.                                            |
 | extended_private | boolean                  |          | Try to read the public key data from the private key object. In some PKCS#11 implementations private key objects have `EC_POINT` attribute. |
 
-**Note**: `public_value` takes precedence over `public`. If none of `public` and `public_value` fields are present then the private key locator `Key Config` will be reused.
+> **Note**: `public_value` takes precedence over `public`. If none of `public` and `public_value` fields are present then the private key locator `Key Config` will be reused.
 
 ### Key Config
 
@@ -41,7 +43,7 @@ title: PKCS#11
 | match_id         | boolean |          | Find the corresponding public key by matching ID.            |
 | extended_private | boolean |          | Try to read the public key data from the private key object. |
 
-**Note**: if the whole object is missing then all options will be assumed as **true**
+> **Note**: if the whole object is missing then all options will be assumed as **true**
 
 ### Environment Variables
 

diff --git a/website/sidebars.js b/website/sidebars.js
@@ -13,34 +13,51 @@
 
 /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
 const sidebars = {
-	// By default, Docusaurus generates a sidebar from the docs folder structure
+  // By default, Docusaurus generates a sidebar from the docs folder structure
 
-	docs: [
-		{
-			type: 'category',
-			label: 'Start',
-			className: 'sidebarHeader',
-			collapsed: false,
-			collapsible: false,
-			items: ['start',
-				'file_based',
-				'yubihsm',
-				'azure_kms',
-				'gcp_kms',
-				'aws_kms',
-				'hashicorp_vault',
-				'ledger',
-				'cli',
-				'remote_policy',
-				'architecture',
-				'bakers',
-				{
-					type: 'category',
-					label: 'Client Authorization',
-					items: [`authorized_keys`, `jwt`]
-				}],
-		},
-	],
+  docs: [
+    {
+      type: "category",
+      label: "Start",
+      className: "sidebarHeader",
+      collapsed: false,
+      collapsible: false,
+      items: [
+        "start",
+        "architecture",
+        "bakers",
+        "cli",
+        "remote_policy",
+        {
+          type: "category",
+          label: "Client Authorization",
+          collapsed: false,
+          items: [`authorized_keys`, `jwt`],
+        },
+        {
+          type: "category",
+          label: "Watermark Backends",
+          collapsed: false,
+          items: [`aws_dynamodb`],
+        },
+        {
+          type: "category",
+          label: "Vault Backends",
+          collapsed: false,
+          items: [
+            `hashicorp_vault`,
+            `aws_kms`,
+            `azure_kms`,
+            `gcp_kms`,
+            `yubihsm`,
+            `ledger`,
+            `pkcs11`,
+            `file_based`,
+          ],
+        },
+      ],
+    },
+  ],
 };
 
 module.exports = sidebars;