docs: Add setup instructions for Azure AD storage mappings

.github/workflows/docs-ci-previews.yaml

@@ -2,38 +2,40 @@
 name: "docs.estuary.dev: Deploy PR previews"
 
 on:
-  pull_request:
-    paths:
-      - site/**
-    types:
-      - opened
-      - reopened
-      - synchronize
-      - closed
+    pull_request:
+        paths:
+            - site/**
+        types:
+            - opened
+            - reopened
+            - synchronize
+            - closed
 
 concurrency: preview-${{ github.ref }}
 
 permissions:
-  contents: write
-  pull-requests: write
+    contents: write
+    pull-requests: write
 
 jobs:
-  deploy-preview:
-    runs-on: ubuntu-20.04
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
-        with:
-          node-version: 18
-          cache: npm
-          cache-dependency-path: ./site/package-lock.json
-      - name: Install dependencies
-        working-directory: ./site
-        run: npm ci
-      - name: Build `docs.estuary.dev`
-        working-directory: ./site
-        run: npm run build
-      - name: Deploy preview
-        uses: rossjrw/pr-preview-action@v1
-        with:
-          source-dir: ./site/build/
+    deploy-preview:
+        runs-on: ubuntu-20.04
+        steps:
+            - uses: actions/checkout@v3
+            - uses: actions/setup-node@v3
+              with:
+                  node-version: 18
+                  cache: npm
+                  cache-dependency-path: ./site/package-lock.json
+            - name: Install dependencies
+              working-directory: ./site
+              run: npm ci
+            - name: Build `docs.estuary.dev`
+              working-directory: ./site
+              env:
+                  BASE_URL: /pr-preview/pr-${{ github.event.number }}
+              run: npm run build
+            - name: Deploy preview
+              uses: rossjrw/pr-preview-action@v1
+              with:
+                  source-dir: ./site/build/

site/docs/concepts/README.md

@@ -247,7 +247,7 @@ A given capture or materialization may have multiple bindings, which connect mul
 Flow [collections](#collections) use cloud storage buckets for the durable storage of data.
 Storage mappings define how Flow maps your various collections into your storage buckets and prefixes.
 
-[Learn more about storage mappings](./storage-mappings.md)
+[Learn more about storage mappings](./storage-mappings/index.md)
 
 
 ## Advanced concepts

site/docs/concepts/advanced/journals.md

@@ -105,7 +105,7 @@ collections:
         retention: 720h
 ```
 
-Your [storage mappings](../storage-mappings.md) determine
+Your [storage mappings](../storage-mappings/index.md) determine
 which of your cloud storage buckets is used
 for storage of collection fragment files.
 

site/docs/concepts/advanced/shards.md

@@ -65,4 +65,4 @@ However, they can hold your user data.
 Recovery logs of [derivations](../derivations.md) hold your derivation register values.
 
 Recovery logs are stored in your cloud storage bucket,
-and must have a configured [storage mapping](../storage-mappings.md#recovery-logs).
+and must have a configured [storage mapping](../storage-mappings/index.md#recovery-logs).

site/docs/concepts/collections.md

@@ -349,7 +349,7 @@ regular JSON files in your cloud storage bucket.
 Reads of that history are served by
 directly reading files from your bucket.
 
-Your [storage mappings](storage-mappings.md)
+Your [storage mappings](./storage-mappings/index.md)
 determine how Flow collections are mapped into
 your cloud storage buckets.
 

site/docs/concepts/schemas.md

@@ -327,7 +327,7 @@ reduce: { strategy: merge }
 ```
 
 Learn more in the
-[reductions strategies](../../../reference/reduction-strategies/)
+[reductions strategies](../../reference/reduction-strategies/)
 reference documentation.
 
 #### Reductions and collection keys

site/docs/concepts/storage-mappings/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Storage Mappings",
+  "position": 4
+}

site/docs/concepts/storage-mappings/azure-blob.mdx

@@ -0,0 +1,42 @@
+---
+sidebar_position: 2
+title: Azure Blob Storage
+---
+
+Setting up a Flow account to store data in your Azure Blob storage account requires you to grant our application access to your storage account and container, as well as providing us with some identifying information. At the moment storage mappings are not self-service, so once you have granted access and gathered the required information, reach out to your account manager who will configure your account.
+
+### Gathering information
+
+In order to complete this process, you will need to gather the following data:
+
+-   Your **Azure AD tenant ID**. This can be found in the "Azure Active Directory" page here:
+    ![](Azure_AD_Tenant_ID.png)
+-   Your **Azure Blob Storage account ID**. This can be found in the "Storage Accounts" page here:
+    ![](Azure_Storage_Account_Name.png)
+-   Your **Azure Blob Storage container ID**. This can be found inside your storage account here:
+    ![](Azure_Container_ID.png)
+
+### Granting Access
+
+We use an [Azure Application](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/what-is-application-management) to allow granting access to storage resources between your tenant and ours. In order for Flow to write to your storage account, it needs the [`Storage Blob Data Owner`](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#storage-blob-data-owner) IAM role for the storage account in question. In order to grant this role, you must first add our application to your tenant.
+
+#### Add application to your tenant
+
+import { AzureAuthorizeComponent } from "./azureAuthorize";
+import BrowserOnly from "@docusaurus/BrowserOnly";
+
+<BrowserOnly>{() => <AzureAuthorizeComponent />}</BrowserOnly>
+
+#### Authorize application to your storage account
+
+Once the application has been added, you must grant it the [`Storage Blob Data Owner`](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#storage-blob-data-owner) IAM role for your storage account.
+
+-   Inside your storage account's "Access Control (IAM)" tab, click "Add Role Assignment"
+-   Search for the string `Storage Blob Data Owner` and select it
+-   On the next page, make sure `User, group, or service principal` is selected, then click "+ Select Members"
+-   You must search for the exact name of the application, otherwise it won't show up: `Estuary Storage Mappings Prod`
+-   Once you've selected the application, finish granting the role and you should be all set
+
+### Give us a ring
+
+Once you've finished the above steps, the next part is to contact us. Self-service storage mapping configuration is on our roadmap, but for the moment we're happy to configure your account by hand. Send [email protected] an email containing all of the information you gathered above, as well as whether you want the storage mapping to apply to your whole Flow account, or just a subset of it. We'll get back to you letting you know when it's done, and that's it!

site/docs/concepts/storage-mappings/azureAuthorize.jsx

@@ -0,0 +1,53 @@
+import React from "react";
+
+export const AzureAuthorizeComponent = () => {
+    const ourAppId = "42cb0c6c-dab0-411f-9c21-16d5a2b1b025";
+    const redirectUri = window.location.href;
+    const resourceId = "https://storage.azure.com";
+
+    const generateAuthorizeUrl = (theirTenant) =>
+        `https://login.microsoftonline.com/${theirTenant}/oauth2/authorize?client_id=${ourAppId}&response_type=code&redirect_uri=${encodeURIComponent(
+            redirectUri
+        )}&resource_id=${encodeURIComponent(resourceId)}`;
+
+    const [tenant, setTenant] = React.useState("");
+
+    const authCode = React.useMemo(() => {
+        return new URLSearchParams(window.location.search.slice(1)).get("code");
+    }, []);
+
+    if (authCode) {
+        return (
+            <span style={{ color: "green" }}>
+                You have successfully added the application to your tenant
+            </span>
+        );
+    } else {
+        return (
+            <>
+                <span>
+                    Input your <b>Tenant ID</b> and follow the prompts to add
+                    our application to your tenant:
+                </span>
+                <br />
+                <br />
+                <input
+                    placeholder="Tenant ID"
+                    value={tenant}
+                    onChange={(e) => setTenant(e.target.value)}
+                />
+                <a
+                    style={{
+                        marginLeft: 8,
+                        color: tenant.length < 1 ? "inherit" : undefined,
+                    }}
+                    href={
+                        tenant.length > 0 ? generateAuthorizeUrl(tenant) : null
+                    }
+                >
+                    Authorize
+                </a>
+            </>
+        );
+    }
+};

site/docs/concepts/storage-mappings.md → site/docs/concepts/storage-mappings/index.md

@@ -1,13 +1,13 @@
 ---
-sidebar_position: 8
+sidebar_position: 1
 ---
 # Storage mappings
 
 Flow stores the documents that comprise your collections in a cloud storage bucket.
 Your **storage mapping** tells Flow which bucket to use.
 
-Every Flow organization (defined by its [catalog prefix](./catalogs.md#namespace)) has a storage mapping defined during setup.
-When you're provisioned a prefix, your Estuary account manager will help you [set up your storage mapping](../getting-started/installation.md#configuring-your-cloud-storage-bucket-for-use-with-flow).
+Every Flow organization (defined by its [catalog prefix](../catalogs.md#namespace)) has a storage mapping defined during setup.
+When you're provisioned a prefix, your Estuary account manager will help you [set up your storage mapping](../../getting-started/installation.md#configuring-your-cloud-storage-bucket-for-use-with-flow).
 If you have a trial account, your storage mapping is Estuary's secure Google Cloud Storage bucket.
 
 You can set up a bucket lifecycle policy to manage data retention in your storage mapping;

site/docs/concepts/web-app.md

@@ -287,7 +287,7 @@ You typically have just one prefix: your organization name, which you provided w
 If you're a trial user, your prefix is `trial/`, and this tab isn't applicable to you;
 your data is stored temporarily in Estuary's cloud storage bucket for your trial period.
 
-[Learn more about storage mappings.](./storage-mappings.md)
+[Learn more about storage mappings.](./storage-mappings/index.md)
 
 #### Connectors
 

site/docs/getting-started/installation.md

@@ -76,7 +76,7 @@ The token will expire after a predetermined duration. Repeat this process to re-
 
 During your trial period, Flow uses Estuary's cloud storage to temporarily store your data.
 When you upgrade from a trial to an organizational account, you're provisioned a unique [prefix](../concepts/catalogs.md#namespace) in the Flow namespace,
-and transition to using your own cloud storage bucket to store your Flow data. This is called a [storage mapping](../concepts/storage-mappings.md).
+and transition to using your own cloud storage bucket to store your Flow data. This is called a [storage mapping](../concepts/storage-mappings/index.md).
 
 Flow supports Google Cloud Storage and Amazon S3 buckets.
 Before your account manager configures your bucket as your storage mapping, you must grant access to Estuary.

site/docusaurus.config.js

@@ -5,12 +5,17 @@ const lightCodeTheme = require('prism-react-renderer/themes/github');
 const darkCodeTheme = require('prism-react-renderer/themes/dracula');
 const codeImport = require('remark-code-import');
 
+const BASE_URL = process.env.BASE_URL || "/"
+const URL = process.env.URL || "https://docs.estuary.dev"
+
+console.log(`Building for: ${URL}${BASE_URL}`)
+
 /** @type {import('@docusaurus/types').Config} */
 const config = {
   title: 'Estuary Flow',
   tagline: 'Dinosaurs are cool',
-  url: 'https://docs.estuary.dev',
-  baseUrl: '/',
+  url: URL,
+  baseUrl: BASE_URL,
   onBrokenLinks: 'throw',
   onBrokenMarkdownLinks: 'warn',
   favicon: 'img/favicon-2.ico',