@appland/appmap 3.146.0 → 3.147.0

package/built/docs/integrations/atlassian-compass.md

@@ -0,0 +1,25 @@
+---
+layout: docs
+title: Docs - Integrations
+description: "Atlassian Compass is a unified platform for managing distributed software architecture. It supports visualizing OpenAPI docs via SwaggerUI, and enables file pushing through webhooks."
+integrations: true
+name: Atlassian Compass
+step: 1
+---
+
+# Atlassian Compass
+
+[Atlassian Compass](https://www.atlassian.com/software/compass) is a developer experience platform that brings your distributed software architecture and the teams collaborating on them together in a single, unified place. [Compass supports visualizing your OpenAPI docs using SwaggerUI](https://community.atlassian.com/t5/Compass-Alpha-articles/Visualize-your-APIs-in-Compass-with-Swagger-UI/ba-p/1814790) integrated into the main Compass application. After adding your application as a new component in Compass, and after enabling the SwaggerUI app, you can now add an additional task to push the `openapi.yml` file to Compass via a webhook. 
+
+<img class="video-screenshot" src="/assets/img/compass-swagger-ui-config.webp"/> 
+
+After generating an API username and token, create a step in your GitHub Action (or other CI tool) to push the file to Compass using the custom URL in the configuration page. Make sure to store the webhook URL, API user, and API key as [encrypted secrets in your build task.](https://docs.github.com/en/actions/security-guides/encrypted-secrets)
+
+```
+  - name: AppMap Generate OpenAPI Definitions
+    run: npx @appland/appmap@latest openapi --output-file openapi.yml
+  - name: Push OpenAPI to Atlassian Compass
+    run: curl -X PUT ${COMPASS_WEBHOOK_URL} -F file=@openapi.yml --user "$COMPASS_API_USER}:${COMPASS_API_KEY}"
+```
+
+[Refer to the Compass documentation for additional information on how to upload your definitions](https://community.atlassian.com/t5/Compass-Alpha-articles/Visualize-your-APIs-in-Compass-with-Swagger-UI/ba-p/1814790)

package/built/docs/integrations/atlassian-confluence.md

@@ -0,0 +1,51 @@
+---
+layout: docs
+title: Docs - Integrations
+description: "AppMap integrates with Atlassian Confluence to generate interactive software diagrams from run-time data, enhancing documentation and collaboration on software projects."
+integrations: true
+name: Atlassian Confluence
+step: 1
+---
+
+# Atlassian Confluence
+
+AppMap integrates with [Confluence](https://www.atlassian.com/software/confluence), the popular corporate wiki developed by the Atlassian.
+
+Confluence facilitates robust documentation and knowledge sharing. AppMap automatically generates interactive software diagrams from run-time data, ensuring an accurate and up-to-date understanding of code architecture and behavior. This integration leverages the strengths of both platforms enabling teams to better understand, document, and collaborate on their software projects.
+
+## Requirements
+
+1. A project containing AppMap Data.
+  - How to make AppMap Diagrams [in your code editor](/docs/get-started-with-appmap/)
+  - How to make AppMap Diagrams [using a GitHub action](/docs/integrations/github-actions) or in [CircleCI](/docs/integrations/circle-ci)
+2. [The AppMap app for Confluence](https://marketplace.atlassian.com/apps/1233075/appmap-for-confluence). 
+
+## Add AppMap Diagrams to a Document or Blog Post
+
+1. **Enter Edit Mode:** Click the pencil icon to switch to Edit Mode in Confluence.
+  <img class="video-screenshot" src="/assets/img/enter-edit-mode.png"/> 
+
+2. **Attach AppMap File:** Drag and drop the AppMap file from your file system or Finder into the Confluence page.
+  <img class="video-screenshot" src="/assets/img/drag-and-drop-appmap.webp"/> 
+
+3. **Insert AppMap:** Click the plus sign to get the insert menu. Type in and select 'AppMap'.
+  <img class="video-screenshot" src="/assets/img/insert-appmap.webp"/> 
+  A placeholder that looks like this will be added to the page: 
+  <img class="video-screenshot" src="/assets/img/appmap-placeholder-confluence.png"/>
+
+4. **Choose AppMap:** Click the pencil under the placeholder to open the AppMap options.
+  <img class="video-screenshot" src="/assets/img/edit-menu-confluence.png"/>
+   Select the AppMap you want to display from the dropdown menu and it will render.
+  <img class="video-screenshot" src="/assets/img/select-an-appmap-confluence.webp"/>
+    <p class="alert alert-info">  If your AppMap does not render, make sure that you are working on a published document. AppMap Diagrams will not render until the document has been published at least once</p>
+
+5. **Adjust Width (Optional)** The width adjustment controls at the bottom of the AppMap window can be used to view more of the AppMap inline.
+  <img class="video-screenshot" src="/assets/img/width-adjustments-confluence.png"/>
+
+6. **Save Changes:** Click the 'Update' button to apply the changes to your Confluence page.
+  <img class="video-screenshot" src="/assets/img/update-button-confluence.png"/>
+
+7. **Fullscreen Mode (Optional):** Click on the 'full screen' icon in the AppMap use Fullscreen mode.
+  <img class="video-screenshot" src="/assets/img/full-screen-control-confluence.png"/>
+    <p class="alert alert-info"> If at any point you would like some help, <strong><a href="/slack">join us in Slack</a>!</strong> You'll find the AppMap team there, along with other AppMap users.</p>
+

package/built/docs/integrations/circle-ci.md

@@ -0,0 +1,424 @@
+---
+layout: docs
+title: Docs - Integrations
+description: "Use AppMap Analysis within CircleCI to analyze behavioral changes per Pull Request. It offers root cause analysis, API changes tracking, security and performance findings, and more."
+integrations: true
+name: CircleCI
+step: 3
+render_with_liquid: false
+redirect_from: [/docs/setup-appmap-in-ci/in-circleci]
+---
+
+# CircleCI <!-- omit in toc -->
+
+<p class="alert alert-info">
+If at any point you would like some help, <a href="/slack">join us in Slack</a>!
+You'll find the AppMap team there, along with other AppMap users.
+</p>
+
+## Overview <!-- omit in toc -->
+AppMap works with your test cases in CircleCI and a GitHub Action to collect, store, analyze, and report on the behavioral changes within each Pull Request. Tests can execute within your existing CircleCI build job, and AppMap Data can be retrieved by a GitHub Action to analyze the code behavior changes. 
+
+- [How it works](#how-it-works)
+- [Step-by-step walkthrough](#step-by-step-walkthrough)
+  - [Prerequisites](#prerequisites)
+  - [Step 1: Setup AppMap file sync in existing CircleCI Project](#step-1-setup-appmap-file-sync-in-existing-circleci-project)
+  - [Step 2: Setup AppMap GitHub Action for baseline](#step-2-setup-appmap-github-action-for-baseline)
+  - [Step 3: Add AppMap to compare HEAD revision](#step-3-add-appmap-to-compare-head-revision)
+  - [Step 4: Merge Pull Request to enable AppMap](#step-4-merge-pull-request-to-enable-appmap)
+- [Example Project Files](#example-project-files)
+- [Advanced Configuration Options](#advanced-configuration-options)
+  - [Prerequisites](#prerequisites-1)
+  - [Step 1: Add or Update AppMap action to use `repository_dispatch` trigger](#step-1-add-or-update-appmap-action-to-use-repository_dispatch-trigger)
+  - [Step 2: Update your CircleCI build to trigger the GitHub API on a successfully build completion.](#step-2-update-your-circleci-build-to-trigger-the-github-api-on-a-successfully-build-completion)
+- [Next Steps](#next-steps)
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/analysis-github-action.webp"/> 
+
+## How it works
+
+AppMap records the behavior of your test cases when they run in CircleCI and produces AppMap Data that can be copied to a centralized storage repository. An additional step is added in your CircleCI build job to create a tarball of that data and push the resulting file to a centralized object storage or file storage of your control. From there, the AppMap GitHub Action will download those maps and analyze them. AppMap will add comments to your Pull Request with deep insights into the runtime code changes. 
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/circleci-github-arch-diagram.webp"/> 
+
+In this example, the following events will happen:
+
+<b>1) CircleCI builds your application and runs automated test cases and AppMap Data will be created in `tmp/appmap` on the CircleCI runner.</b>
+- A tarball (`tar`) file of the `tmp/appmap` directory is created in the CircleCI runner.
+- This tarball is copied to your chosen centralized location (such as AWS S3 or Azure Blob Storage) for secure storage and retrieval by the AppMap GitHub Action.  
+  
+<b>2) While the CircleCI build is running, the AppMap GitHub Action will also trigger, looking for a baseline archive for comparison.</b>
+  - The AppMap GitHub Action waits until all the complete AppMap Dataset exists on the central storage location before continuing.
+  - This will download the raw AppMap Data archive created by CircleCI in your previous step to generate a baseline archive for comparison.
+
+<b>3) The GitHub Action will analyze the latest maps against the baseline for the pull request.  
+  - The AppMap GitHub Action will provide a full runtime code analysis diff report as a comment in your pull request.</b>
+
+## Step-by-step walkthrough
+
+### Prerequisites
+
+1) AppMap only supports project that have automated test cases. To add AppMap to your project, use either the [AppMap installer CLI](/docs/reference/appmap-client-cli.html#install) or manually add with the [AppMap libraries](/docs/reference).
+   
+2) A centralized storage location (such as Amazon S3 or Azure Blob Storage) for storing the raw AppMap Data archive generated from the test cases. This storage needs write access from CircleCI and read access from GitHub Actions. In this example below we will use Amazon S3.
+
+### Step 1: Setup AppMap file sync in existing CircleCI Project
+
+First, create a branch called `appmap-ci` in your project.  Next, in your CircleCI configuration (generally found at `.circle/config.yml`), add a run action that will create a (`tar`) of your AppMap Data after your test cases are completed. 
+
+```yaml
+- run:
+    name: Create AppMap Data archive
+    command: tar --remove-files -cvzf <<pipeline.git.revision>>.tar tmp/appmap/
+```
+{: .example-code}
+
+Using the CircleCI pipeline value of `<<pipeline.git.revision>>` will give this archive tarball a unique file name based on the SHA the AppMap Data is based on. 
+
+After the archive step, add the necessary steps to authenticate and copy this archive file to your centralized storage location. In our example below, we will authenticate with Amazon AWS to generate temporary credentials and then we will copy this file to the configured bucket.  In this example, copying the tarball to the `s3://circleci-appmaps/` bucket. 
+
+```yaml
+- aws-cli/setup:
+    profile_name: Circle-CI-Write-to-S3
+    role_arn: arn:aws:iam::12345678900:role/Circle-CI-Write-to-S3
+
+- aws-s3/copy:
+    from: <<pipeline.git.revision>>.tar
+    profile_name: Circle-CI-Write-to-S3
+    to: s3://circleci-appmap/
+    arguments: --region us-west-2
+```
+{: .example-code}
+
+[**Example Code Commit**](https://github.com/land-of-apps/circle-ci-example/commit/1b1f2e886c8ca0a166296147b083d3eb500a8c5f)
+
+After you push this commit to your branch, CircleCI will trigger a workflow and you can confirm that the steps all completed successfully.  
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/circle-ci-example-storage.webp"/> 
+
+Once you have confirmed your AppMap Data archive has successfully copied to your centralized file repository, merge this branch and continue to the next step.
+  
+### Step 2: Setup AppMap GitHub Action for baseline
+
+To setup the GitHub Action, create a new branch called `appmap-action` in your repository.
+
+Create a new file with the name `.github/workflows/appmap-analysis.yml`
+
+In this file you can use [this default action example](https://github.com/land-of-apps/rails-7-app/blob/c70b48891f38f92223ec06a654406cb7a6886890/.github/workflows/appmap-analysis.yml#L1-L77). **NOTE** Right now you will only use the first job that is listed in lines 1-77, after we create the baseline archive we'll add the AppMap job below this section.
+
+- Download the AppMap tooling into the runner.
+- Check for an existing baseline AppMap archive stored in your GitHub artifact store.
+- (If no baseline AppMap archive exists) Locate and download the tarball of AppMap Data for the base revision from your chosen centralized data store.
+- (If no baseline AppMap archive exists) Create an AppMap archive of the baseline AppMap Data and store to your GitHub artifact store.
+ 
+Commit your GitHub Action workflow file to your branch and open a new Pull Request which will trigger the action.
+
+After the action completes running successfully, check the action summary and confirm a build artifact has been created like the following screenshot.
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/github-artifact-example.webp"/> 
+
+### Step 3: Add AppMap to compare HEAD revision
+ 
+After the previous step succeeds and the baseline AppMap Data is created, [update the GitHub Action](https://github.com/land-of-apps/rails-7-app/blob/c70b48891f38f92223ec06a654406cb7a6886890/.github/workflows/appmap-analysis.yml#L79-L125) to include a similar job to fetch the AppMap Data for the HEAD revision and additionally analyze the code changes for code quality problems and provide a detailed report into the pull request comments.  
+
+[Review this example commit](https://github.com/land-of-apps/circle-ci-example/pull/2/commits/4ea72bb9c930960dafd38698749a0b1dbc2e9db8) for an example of the additional steps to add to your GitHub Action.
+
+When the build completes successfully, you will see a comment from the GitHub Action.  After merging this Pull Request you will see a similar analysis on each new Pull Request.  
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/initial-report.webp"/> 
+
+Your completed installation should now look like the following [Pull Request Example.](https://github.com/land-of-apps/circle-ci-example/pull/2)
+
+### Step 4: Merge Pull Request to enable AppMap
+
+After you merge this Pull Request, AppMap will execute on each subsequent Pull Request.
+
+With AppMap deployed in your project, AppMap will execute on each Pull Request and provide a detailed runtime code analysis on each new commit.  AppMap performs a thorough analysis of the runtime differences, giving you:
+
+- Root cause analysis of failed tests.
+- Web service API changes, both breaking and non-breaking.
+- New and resolved security findings.
+- New and resolved performance findings.
+- New and resolved findings in other categories: maintainability, reliability, and user-defined rules.
+- "Behavioral diffs" as sequence diagrams showing changed runtime behavior within the PR.
+
+[Example Pull Request with Runtime Code Diff](https://github.com/land-of-apps/rails-7-app/pull/14)
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/analysis-pull-request.webp"/>
+<img class="video-screenshot" src="/assets/img/docs/gh-action/analysis-checks-with-circleci.webp"/> 
+
+## Example Project Files
+
+- [Example Ruby on Rails Project](https://github.com/land-of-apps/rails-7-app/)
+- [Pull Request with Runtime Code Diff](https://github.com/land-of-apps/rails-7-app/pull/14)
+- [CircleCI Example copying AppMap Data archive to Amazon S3](https://github.com/land-of-apps/rails-7-app/blob/c70b48891f38f92223ec06a654406cb7a6886890/.circleci/config.yml#L34-L46)
+- [GitHub Action Workflow File](https://github.com/land-of-apps/rails-7-app/blob/c70b48891f38f92223ec06a654406cb7a6886890/.github/workflows/appmap-analysis.yml)
+
+## Advanced Configuration Options
+
+In our basic CircleCI example above, both the CircleCI test runner and the AppMap action will start running at the same time. The GitHub Action will check your central storage location every 10 seconds until your baseline maps and HEAD revision maps exist. For many projects where your test cases can complete in a short amount of time, this additional wait time in the AppMap GitHub Action is worth the cost for the simpler configuration to get started. 
+
+But if your test cases on CircleCi take longer to run, it can be inefficient and expensive to have a GitHub Action running and waiting for files to become available. You can use the GitHub API to trigger a webhook event called `repository_dispatch` when you want to trigger a workflow for activity that happens outside of GitHub. In our case after CircleCI has successfully finished running test and pushed the AppMap archive to the central file storage location. 
+
+Refer to the [GitHub Action documentation](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#repository_dispatch) for more details about how the `repository_dispatch` action trigger works.
+
+The overall architecture largely stays the same as the basic example from above. You can see in the diagram below we've added a new step #2 where a CircleCI job will make a call to the GitHub API to trigger a webhook and start our updated GitHub Action. 
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/advanced-circleci-github-arch-diagram.webp"/> 
+
+### Prerequisites
+
+- [Create a GitHub Personal Access Token](https://docs.github.com/en/enterprise-server@3.8/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) with the `repo` scope. This needs to be stored in your CircleCI account as an environment variable.
+- The `repository_dispatch` trigger will only run if your workflow file is on your main branch. As such, you'll need the ability to commit to your project main branch. 
+- Centralized storage setup and configured for access.  As the example above, you'll need write access from CircleCI and read access from GitHub Actions. In our example we'll be using Amazon S3.
+- This walkthrough assumes you have already completed the basic setup steps in the previous example. At the very least you need to ensure you've [completed Step 2](/docs/setup-appmap-in-ci/in-circleci.html#step-2-setup-appmap-github-action-for-baseline) and have a baseline AppMap archive ready for analysis. 
+
+### Step 1: Add or Update AppMap action to use `repository_dispatch` trigger
+
+For this updated GitHub Action to work you'll need to commit a software utility to your project that will locate which Pull Request your commit is associated with.  Normally when a Pull Request is opened, the AppMap Action will trigger and the action payload will include details about which Pull Request the AppMap report will be associated with.  But since our action will be triggered via a webhook, it will lack information about what Pull Request is associated with the commit. 
+
+#### Add `searchPullRequest.js` to your project <!-- omit in toc -->
+
+You can use this JavaScript function to locate the Pull Request for your commits, and pass the relevant pull request number to the AppMap GitHub Action. [Copy the latest version from the sample project](https://github.com/land-of-apps/rails-7-app/blob/d098acdc0b3d327ebf8c9d062bedb5c779d18008/searchPullRequest.js) and add to your project. 
+
+Add the following as a new file named `package.json` or add these project dependencies to your existing `package.json`
+
+```json
+{
+  "dependencies": {
+    "@octokit/rest": "^20.0.2",
+    "yargs": "^17.7.2"
+  }
+}
+```
+{: .example-code}
+
+#### Add/Update the AppMap Action to your project <!-- omit in toc -->
+
+The most recent version of the AppMap GitHub Action that can be triggered via a [webhook is located in our sample project.](https://github.com/land-of-apps/rails-7-app/blob/cca7f276cf7c32b4b7a5af218ccf19399084777a/.github/workflows/analyze-maps-from-circleci.yml) You'll need to commit this file (configured for your environment) and the files above into the main branch of your repository.  As with the above example you'll need to save this file into the `.github/workflows/` folder. 
+
+**Commit these files to your main branch and then continue to Step 2.**
+
+This action has many steps to process the files and analyze your pull requests, below are details of what each step is doing.
+
+* Reconfigure this environment variable to point to your specific central file location.
+  
+```yaml
+env:
+  appmap_storage_bucket: circleci-appmaps
+```
+{: .example-code}
+
+* Use this action to set the status of your Pull Request as "pending" for the commit being built.
+
+```yaml
+- name: Set commit status as pending
+  uses: myrotvorets/set-commit-status-action@f8a3f50eca0d32f3e12dc3a98792bb588bf29626
+  with:
+    token: ${{ secrets.GITHUB_TOKEN }}
+    status: pending
+    context: AppMap Analysis
+    sha: ${{ github.event.client_payload.head_sha }}
+```
+{: .example-code}
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/appmap-analysis-status.webp"/> 
+
+
+* Install the AppMap command line tools, but do not install the libraries. 
+  
+```yaml
+ - name: Install AppMap tools
+   uses: getappmap/install-action@v1
+   with:
+     install-appmap-library: false
+```
+{: .example-code}
+
+* Check and see if the baseline AppMap archive exists in the GitHub artifact store. This will fail if an archive is not found so we enable `continue-on-error: true`
+  
+```yaml
+- name: Check for existing baseline archive
+  id: check_for_baseline
+  env:
+    GITHUB_TOKEN: ${{ github.token }}
+  continue-on-error: true  
+  run: |
+    appmap restore --check --revision ${base_sha} --github-repo ${GITHUB_REPOSITORY} --exact 
+```
+{: .example-code}
+
+* If the previous step "fails" (i.e. no baseline archive exists) run these steps to download the raw AppMap Data archive and archive them for analysis.
+
+```yaml
+- name: Download and extract appmap data archive
+  if: steps.check_for_baseline.outcome == 'failure'
+  run: | 
+    aws s3 cp s3://${appmap_storage_bucket}/${base_sha}.tar ${base_sha}.tar 
+    tar xvf ${base_sha}.tar
+    
+- name: Archive AppMap Data archive
+  if: steps.check_for_baseline.outcome == 'failure'
+  uses: getappmap/archive-action@v1
+  with: 
+    revision: ${base_sha}
+```
+{: .example-code}
+
+The 2nd section in the GitHub AppMap Action will trigger when the above steps are successful. Below is an explanation of what each of those steps is used for. 
+
+* As in the previous example, reconfigure the storage bucket location based on where your AppMap Data archive is located.
+
+```yaml
+env:
+  appmap_storage_bucket: circleci-appmaps
+```
+{: .example-code}
+
+* Install Node.js and the packages required to run the `searchPullRequest.js` application.
+  
+```yaml
+- name: Use Node.js
+  uses: actions/setup-node@v2
+  with:
+    node-version: '18'
+
+- name: Install dependencies
+  run: npm ci
+```
+{: .example-code}
+
+* Download and extract the HEAD revision AppMap Data archive sent from CircleCI
+
+```yaml
+- name: Download and extract AppMap Data archive
+  run: | 
+    aws s3 cp s3://${appmap_storage_bucket}/${head_sha}.tar ${head_sha}.tar 
+    tar xvf ${head_sha}.tar
+```
+{: .example-code}
+
+* Run `searchPullRequest.js` and locate the most recent Pull Request with the HEAD sha associated. This value will be stored in $LATESTPR.
+
+```yaml
+- name: Get only the most recent issue with this head commit
+  run: echo LATESTPR=$(node searchPullRequest.js --ownerRepo=${GITHUB_REPOSITORY} --commit=${head_sha}) >> "$GITHUB_ENV"
+
+```
+{: .example-code}
+
+* Analyze the AppMap Data archive and compare the changes between the base and head revisions, passing the `issue-number` to the analyze-action.  
+
+```yaml
+- name: Analyze AppMap Data
+  uses: getappmap/analyze-action@v1
+  with:
+    issue-number: ${{env.LATESTPR}}
+    directory: .
+    base-revision: ${{ github.event.client_payload.base_sha }}
+    head-revision: ${{ github.event.client_payload.head_sha }}
+```
+{: .example-code}
+
+* Update the commit status for this repository_dispatch build.
+
+```yaml
+- name: Update Commit Status
+ uses: myrotvorets/set-commit-status-action@v2.0.0
+ if: always()
+ with:
+   token: ${{ secrets.GITHUB_TOKEN }}
+   status: ${{ job.status }}
+   context: AppMap Analysis
+   sha: ${{ github.event.client_payload.head_sha }}
+```
+{: .example-code}
+
+The commit status update will look like the following in a successful pull request.
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/appmap-analysis-status-complete.webp"/> 
+
+Make sure to commit the [searchPullRequest.js](https://github.com/land-of-apps/rails-7-app/blob/d098acdc0b3d327ebf8c9d062bedb5c779d18008/searchPullRequest.js), the [package.json](https://github.com/land-of-apps/rails-7-app/blob/d098acdc0b3d327ebf8c9d062bedb5c779d18008/package.json), and the Webhook AppMap GitHub Action before continuing to step 2.
+
+[Here is an example commit with the changes files in an example test project.](https://github.com/land-of-apps/circle-ci-example/commit/44bcfafbaf978484fc0d29e826d28161ded89ef6)
+
+### Step 2: Update your CircleCI build to trigger the GitHub API on a successfully build completion.  
+
+For an example of a full CircleCI workflow, [refer to the latest version from our sample project.](https://github.com/land-of-apps/rails-7-app/blob/235f97aa4225f4e6e43715b404182f1df7d5c6f5/.circleci/config.yml)
+
+In our example, we'll modify the CircleCI build runner from our basic example, and add a new build job called `run_appmap_analysis` which will only trigger on non-mainline code commits after the normal build succeeds.  
+
+We don't need to trigger the Webhook based AppMap Action on a mainline branch build because analysis only happens inside of an existing Pull Request. 
+
+First we can create a new job in our existing `.circleci/config.yml` file. 
+
+You'll need to update the following items according to your project:
+
+- Ensure your GitHub Personal Access Token is saved as a CircleCI secure environment variable at `$GITHUB_PAT`
+- Update the URL for triggering the `repository_dispatch` project.  The format is: `https://api.github.com/repos/{ORGNAME}/{REPONAME}/dispatches`
+- [Confirm the name of your `repository_dispatch`](https://github.com/land-of-apps/rails-7-app/blob/235f97aa4225f4e6e43715b404182f1df7d5c6f5/.github/workflows/analyze-maps-from-circleci.yml#L3-L7) action and update the `"event_type": "run_appmap_analysis",` accordingly. 
+
+```yaml
+run_appmap_analysis:
+  docker:
+    - image: cimg/ruby:3.1.2
+
+  steps:
+    - checkout
+
+    - run:
+        name: Get base Git SHA
+        command: echo 'export BASE_SHA=$(git merge-base origin/main $CIRCLE_BRANCH)' >> $BASH_ENV
+
+    - run:
+        name: Run AppMap Analysis
+        command: |
+          curl -L \
+            -X POST \
+            -H "Accept: application/vnd.github.v3+json" \
+            -H "Authorization: token $GITHUB_PAT" \
+            -H "Content-Type: application/json" \
+            -H "X-GitHub-Api-Version: 2022-11-28" \
+            https://api.github.com/repos/land-of-apps/rails-7-app/dispatches \
+            -d @- \<<EOF 
+          {
+            "event_type": "run_appmap_analysis",
+            "client_payload": {
+              "base_sha": "$BASE_SHA",
+              "head_sha": "<< pipeline.git.revision >>"
+            }
+          }
+          EOF
+```
+{: .example-code}
+
+In your CircleCI workflow declaration section. Update the jobs so that the GitHub webhook job will only run after the build job and excluding your mainline branch. 
+
+```yaml
+workflows:
+  build:
+    jobs:
+      - build
+      - run_appmap_analysis:
+          requires:
+            - build
+          filters:
+            branches:
+              ignore:
+                - main
+```
+{: .example-code}
+
+Now, create a new Pull Request with these changes and on your next CircleCI build, you'll see that the `run_appmap_analysis` job will execute after your normal build step.  
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/circleci-build-example.webp"/> 
+
+For more details refer to this [example Pull Request](https://github.com/land-of-apps/circle-ci-example/pull/3) and [commit changes](https://github.com/land-of-apps/circle-ci-example/pull/3/commits/8c328130e0572a0eee9b9a0e0b1b2d73e3909ebc) for this sample project. 
+
+When you view your project's GitHub Actions page, you'll see the `workflow_dispatch` action trigger after CircleCI completes its build after it has uploaded the AppMap Data archive to your centralized data store.  
+
+<img class="video-screenshot" src="/assets/img/docs/gh-action/github-action-webhook-example.webp"/> 
+
+## Next Steps
+
+AppMap comes with a comprehensive set of rules that are categorized by their impact on applications: Performance, Reliability, Maintainability, Stability, and Security.  [Refer to the AppMap documentation](/docs/setup-appmap-in-ci/in-github-actions.html#configure-additional-appmap-analysis-rules) to learn how to configure these rules for your project. 

package/built/docs/integrations/docker.md

@@ -0,0 +1,109 @@
+---
+layout: docs
+title: Docs - Integrations
+description: "Learn how to record AppMap Data inside a Docker container for consistent, reproducible environments across various operating systems, enhancing code quality and collaboration."
+integrations: true
+name: Docker
+step: 7
+---
+
+# Docker
+
+AppMap supports capturing AppMap recordings from inside a Docker container, when using [Docker Compose](https://docs.docker.com/compose/), or when running [Docker Desktop](https://www.docker.com/products/docker-desktop/).
+
+- [Why record AppMap Data within Docker?](#why-record-appmap-data-within-docker)
+- [Sample Project](#sample-project)
+- [How to run AppMap inside of Docker Engine](#how-to-run-appmap-inside-of-docker-engine)
+- [How to run AppMap inside of Docker Compose](#how-to-run-appmap-inside-of-docker-compose)
+- [Troubleshooting AppMap and Docker](#troubleshooting-appmap-and-docker)
+
+## Why record AppMap Data within Docker?
+
+Recording AppMap Data inside a Docker container offers several advantages for developers. Docker's containerization ensures a consistent, reproducible environment across various operating systems, which is crucial for diagnosing and resolving issues that may be environment-specific. This uniformity simplifies the setup process, reduces the time spent on environment configuration, and increases the reliability of recorded AppMap Diagrams by mirroring the conditions under which software runs in production or other developers' environments. 
+
+Overall, using Docker for recording AppMap Data streamlines the development workflow, enhances code quality, and fosters collaboration among team members by ensuring that everyone works within an identical development setup.
+
+## Sample Project
+
+To see an example project using Docker and configured with AppMap, you can see the necessary configuration available on our [sample project on GitHub](https://github.com/land-of-apps/sample_rails_app/).
+
+- [Example Dockerfile](https://github.com/land-of-apps/sample_rails_app/blob/main/Dockerfile)  
+- [Example docker-compose.yml](https://github.com/land-of-apps/sample_rails_app/blob/main/docker-compose.yml)
+
+## How to run AppMap inside of Docker Engine
+
+Using the example [Dockerfile](https://github.com/land-of-apps/sample_rails_app/blob/main/Dockerfile) above you need to make sure that you run Docker with the `-v` or `--volume` options in `docker run`.
+
+For example to run the application with AppMap enabled in the sample project above, you will need to run:
+
+```
+> docker run -p 3000:3000 -v $(pwd)/tmp/appmap:/app/tmp/appmap sample_rails_docker bundle exec rails server -b 0.0.0.0
+```
+{: .example-code}
+
+Let's breakdown what that command is doing:
+
+- `docker run`: Command to create and start a new container.  
+- `-p 3000:3000`: Maps port 3000 on the host to port 3000 in the container.  
+- `-v $(pwd)/tmp/appmap:/app/tmp/appmap`: Mounts the tmp/appmap directory from the current directory on the host to /app/tmp/appmap in the container for file sharing.  
+**NOTE** Update `/app/` in the command to where your application is configured to run.  
+- `sample_rails_docker`: The name of the Docker image to use for the container.  
+- `bundle exec rails server -b 0.0.0.0`: The command executed within the container to start the application.  
+
+After recording your AppMap Data, you'll now see them in the VS Code or JetBrains extension.  The maps will also be visible in your local directory in the `tmp/appmap` folder.  
+
+<img class="video-screenshot" src="/assets/img/docs/guides/docker-appmaps.webp"/> 
+
+## How to run AppMap inside of Docker Compose
+
+Using the example [docker-compose.yml](https://github.com/land-of-apps/sample_rails_app/blob/main/docker-compose.yml) file in our sample project. Here is the relevant part of the config.
+
+```
+services:
+  web:
+    build: .
+    command: bundle exec rails server -b 0.0.0.0
+    ports:
+      - "3000:3000"
+    volumes:
+      - ./tmp/appmap:/app/tmp/appmap
+```
+{: .example-code}
+
+Let's explain the main part of our relevant configuration.
+
+services: Defines the services that make up your application.
+
+- `web`: The name of the first (and in this case, only) service.  
+- `build: .`: Tells Docker to build the Docker image for the web service using the Dockerfile in the current directory.  
+- `command: bundle exec rails server -b 0.0.0.0`: Overrides the default command to start the Rails server, making it accessible from any IP address.  
+- `ports: "3000:3000"`: Maps port 3000 on the host to port 3000 in the container, allowing access to the application via localhost:3000.  
+- `volumes: ./tmp/appmap:/app/tmp/appmap`: Mounts the tmp/appmap directory from the host into the container at /app/tmp/appmap for file sharing.  
+**NOTE** Update `/app/` in the command to where your application is configured to run.  
+
+You can now run `docker compose up web` to launch this container using Docker Compose.  When interacting with the application your maps will be displayed in the VS Code or JetBrains plugin.  The maps will also be visible in your local directory in the `tmp/appmap` folder.  
+
+<img class="video-screenshot" src="/assets/img/docs/guides/docker-file-share.webp"/> 
+
+
+## Troubleshooting AppMap and Docker
+
+### AppMap Diagrams are not visible in plugin with directory correctly mounted <!-- omit in toc -->
+
+You may experience an issue on Linux where you have correctly bind mounted the `tmp/appmap` directory into your Docker container, but are still unable to see the AppMap Diagrams in your project.  
+
+<img class="video-screenshot" src="/assets/img/docs/guides/docker-no-appmaps.webp"/>
+
+You can confirm this by looking in the `tmp/appmap` directory in your project file directory listing like in the screenshot below:
+
+<img class="video-screenshot" src="/assets/img/docs/guides/docker-maps-directory.webp"/> 
+
+You can see in that screenshot, a list of AppMap files are visible, and if we opened them in the editor, they would be visible as an AppMap.
+
+<img class="video-screenshot" src="/assets/img/docs/guides/docker-open-map.webp"/> 
+
+When using Docker on Linux, developers might encounter a situation where directories mounted inside a Docker container as bind mounts (using the -v or --volume flag) are owned by the root user. This happens because, by default, Docker runs its containers as the root user, unless specified otherwise. As a result, any files or directories created inside the container on these bind mounts will also be owned by root.  Because the AppMap files in `tmp/appmap` are now owned as the `root` user, the AppMap editor extension is unable to index them, which is necessary for them to be visible in the code editor extension.
+
+We recommend reviewing the [Docker official documentation regarding bind mounts](https://docs.docker.com/storage/bind-mounts/) for the most up to date information on the permission settings for linux bind mounts.  
+
+As a Linux user, make sure that the user/group you are running VS Code as also has write access.  For more info, refer to [this blog post](https://techflare.blog/permission-problems-in-bind-mount-in-docker-volume/) which goes into detail about Linux, Docker, and file permissions.