add recipe for independent connector deployments (#675)

docs/recipes/project-config/independent-connector-deployment.mdx

@@ -0,0 +1,141 @@
+---
+sidebar_position: 4
+sidebar_label: Deploy connectors independently
+description: "Learn how to manage independent deployments for connectors and the supergraph"
+keywords:
+  - hasura
+  - hasura ddn
+  - recipe
+  - guide
+  - project configuration
+  - connector
+  - deployment
+  - independent
+seoFrontMatterUpdated: false
+---
+
+# Deploy connectors and supergraph independently
+
+## Introduction
+
+By default, the CLI command to build the supergraph, i.e. [ddn supergraph build create](/cli/commands/ddn_supergraph_build_create.mdx),
+also builds the connectors required by the supergraph for convenience. Though in certain cases, you might want to do
+these steps independently, e.g. when the connectors are self-hosted and not deployed on Hasura DDN.
+
+In this recipe, you'll learn how to manage independent deployments for your connectors and the supergraph.
+
+:::info Prerequisites
+
+Before continuing, ensure you have:
+
+- A [local Hasura DDN project](/getting-started/quickstart.mdx).
+
+:::
+
+## Recipe
+
+### Basics
+
+The supergraph interacts with a connector via the [DataConnectorLink](/supergraph-modeling/data-connector-links.mdx)
+metadata object which contains the NDC schema of the connector along with the URLs where the connector is running.
+
+Hence, to independently manage the connector and supergraph deployments, we need to ensure that the corresponding
+DataConnectorLink object is kept in sync with the connector.
+
+### Step 1. Build the connector
+
+Build and deploy your connector and note the URL of the deployed connector, say `<deployed-connector-url>`.
+
+### Step 2. Update connector URLs in the data connector link
+
+Update the environment variables that correspond to the connector read and write URLs in the data connector link with
+ `<deployed-connector-url>`:
+
+```yaml title="For example: <subgraph-name>/metadata/<connector-link-name>.hml"
+kind: DataConnectorLink
+version: v1
+definition:
+  name: <connector-link-name>
+  #highlight-start
+  url:
+    readWriteUrls:
+      read:
+        valueFromEnv: <CONNECTOR>_READ_URL
+      write:
+        valueFromEnv: <CONNECTOR>_WRITE_URL
+  #highlight-end
+  headers: ...
+```
+
+Update the environment variables in the corresponding env file:
+
+```env title="For example: .env.cloud"
+...
+#highlight-start
+<CONNECTOR>_READ_URL=<deployed-connector-url>
+<CONNECTOR>_WRITE_URL=<deployed-connector-url>
+#highlight-end
+...
+```
+
+### Step 3. Build the supergraph without connectors
+
+Build the supergraph to get a supergraph build using the connector deployed above:
+
+```bash title="Create supergraph build on DDN without building the related connectors:"
+#highlight-start
+ddn supergraph build create --no-build-connectors \
+#highlight-end
+  --supergraph supergraph.yaml \
+  --env-file .env.cloud \
+  --project <project-name>
+```
+
+:::info
+
+The `--project`, `--supergraph` and `--env-file` flags can be skipped if the keys `project`, `supergraph` and
+`cloudEnvFile` are set in the context.
+
+:::
+
+### Step 4. (Optional) Add a custom script to build the supergraph
+
+You can add the above command as a [custom script](/project-configuration/custom-scripts.mdx) to avoid having to pass
+the `--no-build-connectors` flag each time.
+
+For example, you can update your context config to the following:
+
+```yaml title="<project-root>/.hasura/context.yaml:"
+kind: Context
+version: v3
+definition:
+  current: default
+  contexts:
+    default: ...
+  scripts:
+    docker-start:
+      bash: HASURA_DDN_PAT=$(ddn auth print-pat) docker compose --env-file .env up --build --pull always -d
+      powershell: $Env:HASURA_DDN_PAT = (ddn auth print-pat); docker compose --env-file .env up --build --pull always -d
+    #highlight-start
+    build-supergraph:
+      bash: ddn supergraph build create --no-build-connectors --supergraph supergraph.yaml --env-file .env.cloud --project <project-name>
+      powershell: ddn supergraph build create --no-build-connectors --supergraph supergraph.yaml --env-file .env.cloud --project <project-name>
+    #highlight-end
+```
+
+Now you can run the following command to build the supergraph:
+
+```bash
+ddn run build-supergraph
+```
+
+:::info
+
+The `--project`, `--supergraph` and `--env-file` flags can be skipped if the keys `project`, `supergraph` and
+`cloudEnvFile` are set in the context.
+
+:::
+
+## Learn more
+
+- [Project configuration](/project-configuration/overview.mdx)