> ## Documentation Index
> Fetch the complete documentation index at: https://nango.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Pre-built integrations for self-managed Nango instances

> Upload Nango's pre-built integration catalog to your own object storage on AWS, GCP or Azure.

The integration catalog is the set of Nango-maintained functions you can browse and deploy from the dashboard. On a [Self-Managed](https://nango.dev/docs/guides/platform/self-hosting/self-managed.md) instance, you upload its compiled files to your own object storage. Until you do, templates show up in the dashboard but fail when you run them.

> [!NOTE]
>
> This page is for **Self-Managed** instances only. If you run [BYOC](https://nango.dev/docs/guides/platform/self-hosting/byoc.md), Nango installs and updates the catalog for you.

## Requirements

* **An access token from Nango.** The integration catalog repository is private. Ask for a token in your shared Slack channel with Nango or email [support@nango.dev](mailto:support@nango.dev).
* Nango managed image `managed-1.6.18` or later.
* An object storage bucket (S3, GCS or Azure Blob Storage) configured for your instance's compiled integration files. See [Configure object storage](#configure-object-storage).
* `git`, `node` and `npm` on the machine that builds the catalog.
* Your cloud provider's CLI, signed in with write access to the bucket, on the machine that uploads the catalog:
  * AWS: [AWS CLI](https://aws.amazon.com/cli/) (`aws`)
  * GCP: [`gsutil`](https://cloud.google.com/storage/docs/gsutil_install)
  * Azure: [AzCopy](https://learn.microsoft.com/azure/storage/common/storage-use-azcopy-v10) (`azcopy`) for uploads and the [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) (`az`) for verification

## Configure object storage

Nango reads the catalog from the same object store it uses for your deployed functions. Set the variables for **one** provider on the server, jobs and runner services. If your instance already deploys functions to object storage, these are already set.

Also set `NANGO_ENTERPRISE=true`. See the [configuration reference](https://nango.dev/docs/guides/platform/self-hosting/self-managed.md#configuration-reference) for the full list of variables.

**AWS (S3)**

| Variable | Example | Purpose |
| - | - | - |
| `AWS_INTEGRATIONS_BUCKET_NAME` | `my-company-nango-integrations` | S3 bucket for compiled integration files |
| `AWS_INTEGRATIONS_REGION` | `us-west-2` | Region of the bucket |

The workloads need permission to read and write objects in the bucket, for example through an IAM role.

**GCP (GCS)**

| Variable | Example | Purpose |
| - | - | - |
| `GCS_INTEGRATIONS_BUCKET_NAME` | `my-company-nango-integrations` | GCS bucket for compiled integration files |

Nango authenticates with Application Default Credentials, so the workloads need permission to read and write objects in the bucket.

**Azure (Blob Storage)**

| Variable | Example | Purpose |
| - | - | - |
| `AZURE_INTEGRATIONS_ACCOUNT_NAME` | `mycompanynango` | Storage account for compiled integration files |
| `AZURE_INTEGRATIONS_CONTAINER_NAME` | `integrations` | Blob container |
| `AZURE_INTEGRATIONS_ACCOUNT_KEY` | `••••••••` | Optional shared key. Omit it to use `DefaultAzureCredential` |

Set the account name and container name together.

> [!NOTE]
>
> Set `NANGO_FLAG_PROVIDER=env` and `NANGO_FEATURE_FLAG_TOOLS_CATALOG=true` on the server and jobs services. Once an object store is configured, Nango reads catalog files from it.

## Install the catalog

**1. Find the matching catalog version**

Each Nango image bundles catalog metadata built from one specific commit of the `integration-templates` repository. The files you upload must come from that same commit, or templates fail at runtime.

To find it, clone the Nango repo and check out the commit your image was built from. That commit is the last part of the image tag:

```
nangohq/nango:managed-1.6.18-0.71.11-fe85242b81ab9d3ac808a72ca7bdd2788c8e86fb
                                     └──────────── Nango commit SHA ────────────┘
```

Check out that commit and read the `integration-templates` commit from the last update to the bundled catalog metadata:

```bash theme={null}
git clone https://github.com/NangoHQ/nango
cd nango
git checkout <NANGO-COMMIT-SHA>
git log -1 --format=%s -- packages/shared/flows.zero.json
```

The SHA at the end of the output is the `integration-templates` commit to use in the next step:

```
chore(integration-templates): automatic update from https://github.com/NangoHQ/integration-templates/commit/<COMMIT-SHA>
```

**2. Build the catalog at that commit**

Clone the `integration-templates` repository, authenticating with your access token. Check out the commit from step 1 and compile:

```bash theme={null}
cd ..  # leave the nango checkout from step 1
git clone https://github.com/NangoHQ/integration-templates
cd integration-templates
git checkout <COMMIT-SHA>
npm ci
npm run compile:integrations
```

This takes several minutes. The script sets its own 8 GB Node heap, so don't override it. The output goes into `integrations/<provider>/build/`.

**3. Verify the build**

The compiled catalog metadata must be **byte-identical** to the metadata bundled in your image. Compare it with the file in the Nango checkout from step 1:

```bash theme={null}
# from the integration-templates directory
shasum -a 256 internal/flows.zero.json
shasum -a 256 ../nango/packages/shared/flows.zero.json
```

The two hashes must match. If they differ, return to step 1, confirm you checked out the Nango commit from your image tag, and rebuild.

**4. Upload to your bucket**

Upload each provider's folder to the `templates-zero/` prefix in your bucket, so that `integrations/github/...` ends up at `templates-zero/github/...`.

**AWS (S3)**

```bash theme={null}
BUCKET=<your-bucket>

for dir in integrations/*/; do
  [ -d "$dir/build" ] || continue
  integration=$(basename "$dir")
  aws s3 sync "$dir" "s3://$BUCKET/templates-zero/$integration"
done
```

`aws s3 sync` uploads in parallel. Add `--delete` to also remove files that no longer exist in the catalog.

**GCP (GCS)**

```bash theme={null}
BUCKET=<your-bucket>

for dir in integrations/*/; do
  [ -d "$dir/build" ] || continue
  integration=$(basename "$dir")
  gsutil -m rsync -r "$dir" "gs://$BUCKET/templates-zero/$integration"
done
```

`-m` uploads in parallel. Add `-d` to also remove files that no longer exist in the catalog.

**Azure (Blob Storage)**

Use [AzCopy](https://learn.microsoft.com/azure/storage/common/storage-use-azcopy-v10), not `az storage blob upload-batch`. The Azure CLI uploads blobs one at a time, which turns a full catalog into an hour-long step. AzCopy uploads in parallel and finishes in minutes.

```bash theme={null}
# Reuse your existing `az login` session
export AZCOPY_AUTO_LOGIN_TYPE=AZCLI

for dir in integrations/*/; do
  [ -d "$dir/build" ] || continue
  azcopy copy "$dir" \
    "https://<ACCOUNT>.blob.core.windows.net/<CONTAINER>/templates-zero/" \
    --recursive
done
```

Authenticating through Microsoft Entra instead of an account key also works when shared key access is disabled on the storage account.

AzCopy doesn't delete files that were removed from the catalog. A template removed upstream stays in the container until you delete it.

Uploads overwrite existing files, so it's safe to run them again.

**5. Verify the install**

First, check that a known file exists in your bucket:

**AWS (S3)**

```bash theme={null}
aws s3 ls "s3://$BUCKET/templates-zero/github/build/github_actions_create-issue.cjs"
```

**GCP (GCS)**

```bash theme={null}
gsutil ls "gs://$BUCKET/templates-zero/github/build/github_actions_create-issue.cjs"
```

**Azure (Blob Storage)**

```bash theme={null}
az storage blob exists \
  --account-name <ACCOUNT> \
  --container-name <CONTAINER> \
  --auth-mode login \
  --name "templates-zero/github/build/github_actions_create-issue.cjs"
```

Then confirm it works end to end:

1. In the dashboard, open an integration with templates provided by Nango (see [Use the template catalog](https://nango.dev/docs/guides/functions/functions-guide.md#option-1-use-the-template-catalog)).
2. Select an action with source "Nango catalog".
3. Run the selected action via the [Trigger action API](https://nango.dev/docs/reference/backend/http-api/action/trigger.md) or using the "Test run" button.

## Update the catalog

When you upgrade your image, repeat the [install steps](#install-the-catalog) with the new image tag. Your access token stays valid, so you don't need to contact Nango again. Templates you already deployed keep the files they were deployed with, so deploy them again to pick up the new version.

## Troubleshooting

| Symptom | Likely cause |
| - | - |
| A template appears in the dashboard but the function stays `in progress` | The files aren't in the bucket, or they came from a different commit than the one your image expects. Redo steps 1 to 4. |
| Template deploys fail on every attempt, even with files uploaded | Your image is older than `managed-1.6.18`. Upgrade first. |

## Related guides

* [Self-Managed](https://nango.dev/docs/guides/platform/self-hosting/self-managed.md) - deployment, configuration reference and updates.
* [BYOC](https://nango.dev/docs/guides/platform/self-hosting/byoc.md) - Nango manages the catalog for you.
* [Self-hosting overview](https://nango.dev/docs/guides/platform/self-hosting) - architecture and object storage.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.