SitecoreDXG Documention
  • SitecoreDXG: The Documentation Experience Generator
  • Overview
    • SitecoreDXG: The Documentation Experience Generator
    • Comparison with SitecoreUML
    • CI/CD Integration
    • Helix Dependency Validation
  • Getting Started
    • Compatibility and System Requirements
    • Installing SitecoreDXG
      • General Installation
        • 1. Install the SitecoreDXG Generation Service
        • 2. Install RabbitMQ
        • 3. Install the SitecoreUML Service for Sitecore
        • 4. (Optional) Configure the Documentation Configuration Item for your Solution
        • 5. Install the Default RabbitMQ Middleman in a Custom Location
        • 6. (Optional) Integrate SitecoreDXG into your CI/CD Pipeline
      • Developer Installation
        • 1. Install the SitecoreDXG Generation Service for Developers
        • 2. Install RabbitMQ for Developers
        • 3. Install the SitecoreUML Service for Sitecore for Developers
        • 4. (Optional) Configure the Documentation Configuration Item for your Solution
        • 5. (Optional) Install the Default RabbitMQ Middleman for Developers
        • 6. (Optional) Integrate SitecoreDXG into your CI/CD Pipeline for Developers
    • Upgrading and Downgrading
    • Downloads
    • Using SitecoreDXG
      • Using the Default RabbitMQ Middleman and Trigger
        • Using the DocumentationConfiguration Object
      • Using the Provided AWS S3 Deploy Completion Handler
      • Using the Provided Azure Blob Storage Deploy Completion Handler
  • Architecture
    • Architecture Overview
    • Roles
      • Role Combinations
    • Components
    • Plugins
      • Trigger Plugins
      • Completion Handler Plugins
    • Middlemen
    • Understanding the Default RabbitMQ Middleman and Trigger
  • How To
    • CI/CD Integration
      • Integrating SitecoreDXG into your CI/CD Pipeline
      • Integrating the Default TeamCity RabbitMQ Meta-Runner
    • Creating a Custom Trigger
      • Executing Documentation Generation
      • Executing Meta-Data JSON Generation
    • Slack and Microsoft Teams Integration
      • Integrating with Slack via Webhooks
      • Integrating with Microsoft Teams via Webhooks
    • Creating a Custom Completion Handler
    • Creating a Custom Middleman
    • Viewing Helix Validation Errors
  • About the Generated Documentation
    • Overview
    • Models
      • Template Model
      • Template Field Model
      • Template Folder Model
      • Parent-Child Relationships of Models
      • Inheritance Relationship Model
      • Dependency Relationship Model
    • Views
      • Template View
      • Template Field View
      • Template Folder View
      • Parent-Child Relationship View
      • Inheritance Relationship View
      • Dependency Relationship View
    • Diagrams
      • SitecoreUML Syntax
      • Templates Diagram
      • Template Folders Diagram
      • Layer Diagrams
      • Module Diagrams
      • Module Templates Diagrams
    • Samples
Powered by GitBook
On this page
  • Setup
  • Parameters
  • Important Note About Folders in AWS S3
  • Calling the S3 Deploy Handler Data from the Middleman
  1. Getting Started
  2. Using SitecoreDXG

Using the Provided AWS S3 Deploy Completion Handler

PreviousUsing the DocumentationConfiguration ObjectNextUsing the Provided Azure Blob Storage Deploy Completion Handler

Last updated 6 years ago

SitecoreDXG includes the AWS S3 Deploy Completion Handler for deploying the generated output to an AWS S3 bucket. Using this completion handler, you can rapidly configure your CI/CD infrastructure to generate updated Sitecore template architecture documentation on every build, and then publish the generated HTML-based documentation to AWS for live viewing. This ensures that you always have an up-to-date and live documentation site for your architecture that you can optionally share with clients, internal teams, or other groups and individuals.

Setup

  1. Go to the and create and/or retrieve the details for the AWS S3 bucket and user that you intend to use

    1. Create a new S3 bucket if you don't already have one that you intend to use

    2. In the AWS Console, create an IAM user with access to the bucket, if you don't already have one that you intend to use, and record the access key ID and secret access key for later use

    3. Configure the policy and management settings for your AWS S3 Bucket so that it can be served as a static website. The following is the JSON for a policy that could be used for a bucket named "mybucket":

      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Sid": "PublicReadGetObject",
                  "Effect": "Allow",
                  "Principal": "*",
                  "Action": "s3:GetObject",
                  "Resource": "arn:aws:s3:::mybucket/*"
              }
          ]
      }
    4. Configure the policy for your IAM user or its group (group recommended) so that the you can upload, download, list and delete objects to/from the S3 bucket. The following is the JSON for a policy that could be used to give a user/group the necessary access to a bucket named "mybucket":

      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Sid": "AllowUserReadWriteDeleteListDataObjectForMyBucketS3",
                  "Effect": "Allow",
                  "Action": [
                      "s3:PutObject",
                      "s3:ListBucket",
                      "s3:GetBucketLocation",
                      "s3:DeleteObject"
                  ],
                  "Resource": [
                      "arn:aws:s3:::*/*",
                      "arn:aws:s3:::mybucket"
                  ]
              }
          ]
      }
  2. (Optional) if you wish to set the completion handler as the default then update the DefaultCompletionHandlers property in the ./settings.js file of the SitecoreDXG Generation Service with required settings for calling the completion handler

  3. If you are running the SitecoreDXG Generation Service as a Windows service then you need to restart the service

WARNING: You should always deploy to an empty directory

The AWS S3 Deploy Completion Handler is designed to perform clean deployments, meaning that any files in the targeted S3 folder will be deleted immediately prior to the deployment. You can use the S3FolderPath parameter to set the target deployment location to somewhere other than the bucket's root (the default). Note that anything in the target directory (or the root if the target directory is not set) will be deleted.

Parameters

The AWS S3 Deploy Completion Handler requires a JSON parameters object with the following syntax:

{
    "AccessKeyId": "YOUR_AWS_ACCESS_KEY_ID",
    "SecretAccessKey": "YOUR_AWS_SECRET_ACCESS_KEY",
    "S3BucketName": "MyS3Bucket",
    "S3FolderPath": "MySite/UAT"
}
[{
    "ID": "AWS_S3",
    "Params": {
        "AccessKeyId": "YOUR_AWS_ACCESS_KEY_ID",
        "SecretAccessKey": "YOUR_AWS_SECRET_ACCESS_KEY",
        "S3BucketName": "MyS3Bucket",
        "S3FolderPath": "MySite/UAT"
    }
}]

Important Note About Folders in AWS S3

The S3 buckets in AWS don't have a real concept of "folders", but S3 can be made to behave similar to the way you would expect it to if it did have folders, so long as you use a forward slash (/) as the delimiter of your path slugs. For example, in the above, the value "MySite/UAT" will effectively function as though the /UAT folder is a subdirectory of /MySite.

Calling the S3 Deploy Handler Data from the Middleman

This section describes how you can call the S3 Deploy Handler from the default RabbitMQ Middleman as well the provided TeamCity Meta-Runner.

  1. {"CompletionHandlers":[{"ID":"AWS_S3","Params":{"AccessKeyId":"YOUR_AWS_ACCESS_KEY_ID","SecretAccessKey":"YOUR_AWS_SECRET_ACCESS_KEY","S3BucketName":"MyS3Bucket","S3FolderPath":"MySite/UAT"}}]}
  2. Save the JSON object to your OPTIONS_FILE_PATH

In order to pass this object to the handler, it should be set as the Params object of the completion handler data in the JSON file at the . The following illustrates the completion handler data object for the AWS S3 Deploy Completion Handler within the completion handler data array:

Complete the steps described in the section, above, on your SitecoreDXG Generation Server

Create your completion handler data object for the S3 Deploy Handler, as described above in the section, for example:

Pass the to the middleman so that it can be passed to the Trigger and subsequently to the Generator

If using the default RabbitMQ middleman: see for more information on the middleman parameters and syntax

If using the provided TeamCity Meta-Runner: see for more information on the fields and syntax

AWS Console
OPTIONS_FILE_PATH
OPTIONS_FILE_PATH
Using the Default RabbitMQ Middleman and Trigger
Integrating the Default TeamCity RabbitMQ Meta-Runner
Setup
Parameters