From 33921a0aba392f8306959d08acbcdac5d4b76ae4 Mon Sep 17 00:00:00 2001 From: Isaac Mann Date: Tue, 17 Sep 2024 09:08:34 -0400 Subject: [PATCH 1/9] docs(core): add aws authentication instructions --- .../powerpack-s3-cache-plugin.md | 88 ++++++++++++++++++- 1 file changed, 86 insertions(+), 2 deletions(-) diff --git a/docs/shared/packages/powerpack-s3-cache/powerpack-s3-cache-plugin.md b/docs/shared/packages/powerpack-s3-cache/powerpack-s3-cache-plugin.md index 51c0779b647d0..80ba95ac9ac8c 100644 --- a/docs/shared/packages/powerpack-s3-cache/powerpack-s3-cache-plugin.md +++ b/docs/shared/packages/powerpack-s3-cache/powerpack-s3-cache-plugin.md @@ -1,6 +1,90 @@ --- title: Overview of the Nx powerpack-s3-cache Plugin -description: The Nx Plugin for esbuild contains executors and generators that support building applications using esbuild. This page also explains how to configure esbuild on your Nx workspace. +description: The powerpack-s3-cache Nx plugin enables you to use an AWS S3 bucket to host your remote cache instead of Nx Cloud --- -Powerpack s3-cache +{% callout title="This plugin requires an active Nx Powerpack license" %} +In order to use `@nx/powerpack-owners`, you need to have an active Powerpack license. If you don't have a license or it has expired, the syncing process will stop working and you'll need to manually maintain your CODEOWNERS file. +{% /callout %} + +## Setup + +### 1. Install the Package + +1. [Activate Powerpack](/recipes/installation/activate-powerpack) if you haven't already +2. Install the package + +```shell +nx add @nx/powerpack-owners +``` + +### 2. Authenticate with AWS + +There are four different ways to authenticate with AWS. They will be attempted in this order: + +1. Environment variables +2. INI config files +3. Single sign-on +4. `nx.json` settings + +#### Environment Variables + +[AWS provides environment variables](https://docs.aws.amazon.com/sdkref/latest/guide/environment-variables.html) that can be used to authenticate: + +| **Environment Variable** | **Description** | +| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AWS_ACCESS_KEY_ID` | The access key for your AWS account. | +| `AWS_SECRET_ACCESS_KEY` | The secret key for your AWS account. | +| `AWS_SESSION_TOKEN` | The session key for your AWS account. This is only needed when you are using temporary credentials. | +| `AWS_CREDENTIAL_EXPIRATION` | The expiration time of the credentials contained in the environment variables described above. This value must be in a format compatible with the [ISO-8601 standard](https://en.wikipedia.org/wiki/ISO_8601) and is only needed when you are using temporary credentials. | + +Both the `AWS_ACCESS_KEY_ID` and the `AWS_SECRET_ACCESS_KEY` environment variables are required to use the environment variable authentication method. + +#### INI Config Files + +AWS can read your authentication credentials from [shared INI config files](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html). The files are located at `~/.aws/credentials` and `~/.aws/config`. Both files are expected to be INI formatted with section names corresponding to profiles. Sections in the credentials file are treated as profile names, whereas profile sections in the config file must have the format of `[profile profile-name]`, except for the default profile. Profiles that appear in both files will not be merged, and the version that appears in the credentials file will be given precedence over the profile found in the config file. + +#### Single Sign-On + +Nx can read the active access token [created after running `aws sso login`](https://docs.aws.amazon.com/sdkref/latest/guide/understanding-sso.html) then request temporary AWS credentials. You can create the `AwsCredentialIdentityProvider` functions using the inline SSO parameters (`ssoStartUrl`, `ssoAccountId`, `ssoRegion`, `ssoRoleName`) or load them from [AWS SDKs and Tools shared configuration and credentials files](https://docs.aws.amazon.com/credref/latest/refdocs/creds-config-files.html). Profiles in the `credentials` file are given precedence over profiles in the `config` file. + +#### Credentials in `nx.json` File + +Storing your credentials in the `nx.json` file is the least secure of the 4 authentication options, since anyone with read access to your code base will have access to your AWS credentials. + +```jsonc {% fileName="nx.json" %} +{ + "s3": { + "ssoProfile": "default", + "accessKeyId": "MYACCESSKEYID", + "secretAccessKey": "MYSECRETACCESSKEY" + } +} +``` + +| **Property** | **Description** | +| ------------------- | ----------------------------------------------------------------------------- | +| **ssoProfile** | The name of the profile to use from your AWS CLI SSO Configuration (optional) | +| **endpoint** | The AWS endpoint URL (optional) | +| **accessKeyId** | AWS Access Key ID (optional) | +| **secretAccessKey** | AWS secret access key (optional) | + +### 3. Configure S3 Cache + +Regardless of how you manage your AWS authentication, you need to configure your Nx cache in the `nx.json` file. The `bucket` that you specify needs to already exist - Nx doesn't create it for you. + +```jsonc {% fileName="nx.json" %} +{ + "s3": { + "region": "us-east-1", + "bucket": "my-bucket", + "encryptionKey": "create-your-own-key" + } +} +``` + +| **Property** | **Description** | +| ----------------- | --------------------------------------------------------------------------------- | +| **region** | The id of the AWS region to use | +| **bucket** | The name of the AWS bucket to use | +| **encryptionKey** | Nx encryption key used to encrypt and decrypt artifacts from the cache (optional) | From e8cc489a192755345703eba7ee79e45d57b88512 Mon Sep 17 00:00:00 2001 From: Isaac Mann Date: Thu, 19 Sep 2024 16:08:09 -0400 Subject: [PATCH 2/9] docs(core): custom cache feature page --- docs/generated/manifests/menus.json | 16 ++++++++++ docs/generated/manifests/nx.json | 22 +++++++++++++ docs/map.json | 5 +++ docs/shared/deprecated/custom-task-runners.md | 12 +++++++ .../features/powerpack/custom-caching.md | 32 +++++++++++++++++++ docs/shared/reference/sitemap.md | 1 + 6 files changed, 88 insertions(+) create mode 100644 docs/shared/deprecated/custom-task-runners.md diff --git a/docs/generated/manifests/menus.json b/docs/generated/manifests/menus.json index 6a32f113aa5e5..9a998c6fdb681 100644 --- a/docs/generated/manifests/menus.json +++ b/docs/generated/manifests/menus.json @@ -4876,6 +4876,14 @@ "children": [], "disableCollapsible": false }, + { + "name": "Custom Task Runners", + "path": "/deprecated/custom-task-runners", + "id": "custom-task-runners", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, { "name": "Workspace Executors", "path": "/deprecated/workspace-executors", @@ -4975,6 +4983,14 @@ "children": [], "disableCollapsible": false }, + { + "name": "Custom Task Runners", + "path": "/deprecated/custom-task-runners", + "id": "custom-task-runners", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, { "name": "Workspace Executors", "path": "/deprecated/workspace-executors", diff --git a/docs/generated/manifests/nx.json b/docs/generated/manifests/nx.json index 6c83108e0ef7d..0da64f8865203 100644 --- a/docs/generated/manifests/nx.json +++ b/docs/generated/manifests/nx.json @@ -6677,6 +6677,17 @@ "path": "/deprecated/workspace-generators", "tags": [] }, + { + "id": "custom-task-runners", + "name": "Custom Task Runners", + "description": "", + "mediaImage": "", + "file": "shared/deprecated/custom-task-runners", + "itemList": [], + "isExternal": false, + "path": "/deprecated/custom-task-runners", + "tags": [] + }, { "id": "workspace-executors", "name": "Workspace Executors", @@ -6814,6 +6825,17 @@ "path": "/deprecated/workspace-generators", "tags": [] }, + "/deprecated/custom-task-runners": { + "id": "custom-task-runners", + "name": "Custom Task Runners", + "description": "", + "mediaImage": "", + "file": "shared/deprecated/custom-task-runners", + "itemList": [], + "isExternal": false, + "path": "/deprecated/custom-task-runners", + "tags": [] + }, "/deprecated/workspace-executors": { "id": "workspace-executors", "name": "Workspace Executors", diff --git a/docs/map.json b/docs/map.json index b50e63dd42391..a73cb84ad906f 100644 --- a/docs/map.json +++ b/docs/map.json @@ -1398,6 +1398,11 @@ "id": "workspace-generators", "file": "shared/deprecated/workspace-generators" }, + { + "name": "Custom Task Runners", + "id": "custom-task-runners", + "file": "shared/deprecated/custom-task-runners" + }, { "name": "Workspace Executors", "id": "workspace-executors", diff --git a/docs/shared/deprecated/custom-task-runners.md b/docs/shared/deprecated/custom-task-runners.md new file mode 100644 index 0000000000000..0336bd0b853ef --- /dev/null +++ b/docs/shared/deprecated/custom-task-runners.md @@ -0,0 +1,12 @@ +# tasksRunnerOptions and cacheDirectory + +As of Nx 20, custom task runners (defined via `tasksRunnerOptions`) and the `cacheDirectory` property in `nx.json` are deprecated. They will cease to function in Nx 21. In Nx 20, the local cache is stored in a database, rather than using the file system. This has two benefits: + +1. Cache reads and writes are faster. +2. The local cache is more secure since other processes with access to the file system can no longer read or modify the cache. + +For most organizations, this feature is a net positive. If you are currently using a custom task runner, you are mostly likely using it to define your own custom [remote cache](/ci/features/remote-cache) storage location. You have several options moving forward: + +1. Use [Nx Cloud](/nx-cloud) for your remote cache +2. Use an [Nx Powerpack](/powerpack) plugin to store your remote cache on an [AWS S3 bucket](/nx-api/powerpack-s3-cache) or a [network drive](/nx-api/powerpack-shared-fs-cache) +3. Use the deprecated custom task runner feature until Nx 21 diff --git a/docs/shared/features/powerpack/custom-caching.md b/docs/shared/features/powerpack/custom-caching.md index 9d22c3bd0ce1e..070b97a5415f5 100644 --- a/docs/shared/features/powerpack/custom-caching.md +++ b/docs/shared/features/powerpack/custom-caching.md @@ -1 +1,33 @@ # Change the Remote Cache Storage Location + +The recommended way to enable the [remote cache]() is to use [Nx Replay]() and have Nx Cloud share the task cache across your organization. For those organizations that are unable to use Nx Cloud, Nx offers official plugins that are enabled by [Nx Powerpack]() to customize your remote cache location in a fast and secure manner. + +In Nx 20, the local cache mechanism is getting faster and more secure by storing the cache in a database instead of directly on the file system. The new cache is faster because it avoids the unavoidably slow speed of interacting with the file system. The new cache is more secure because it eliminates the possibility that other processes with file system access could read or modify the cache. The [`@nx/powerpack-s3-cache`](/nx-api/powerpack-s3-cache) and [`@nx/powerpack-shared-fs-cache`](/nx-api/powerpack-shared-fs-cache) plugins enable you to leverage that speed and security with a custom remote cache storage location. + +{% callout type="note" title="Custom Task Runners are Deprecated in Nx 20" %} +If you have a custom coded method for changing the remote cache location that uses either `tasksRunnerOptions` or `cacheDirectory`, you'll need to choose a migration path. Those properties are [deprecated in Nx 20](/deprecated/custom-task-runners) and will be removed in Nx 21. +{% /callout %} + +## Custom Remote Cache Storage Plugins Require Nx Powerpack + +The `@nx/powerpack-s3-cache` and `@nx/powerpack-shared-fs-cache` plugins require an Nx Powerpack license to function. [Activating Powerpack](/recipes/installation/activate-powerpack) is a simple process. + +{% call-to-action title="Buy a Powerpack License" icon="nx" description="Unlock all the features of Nx" url="https://nx.app/nx-powerpack/purchase" /%} + +## Choose Your Storage Solution + +Read the individual plugin documentation for specific set up instructions. + +{% cards cols="2" lgCols="2" mdCols="2" smCols="2" %} + +{% link-card title="AWS S3 Bucket Remote Cache" type="Nx Plugin" url="/nx-api/powerpack-s3-cache" icon="aws" /%} + +{% link-card title="Shared Network Drive Remote Cache" type="Nx Plugin" url="/nx-api/powerpack-shared-fs-cache" icon="network" /%} + +{% /cards %} + +## Switch to Nx Cloud + +These custom remote cache storage solutions only provide the remote cache functionality of Nx Cloud. If you want to leverage [distributed task execution](), [re-running flaky tasks]() or [automatically splitting tasks](), you'll need to [connect to Nx Cloud]() and use Nx Cloud's remote cache solution instead. + +{% call-to-action title="Connect to Nx Cloud" icon="nxcloud" description="Enable task distribution and Atomizer" url="/ci/intro/connect-to-nx-cloud" /%} diff --git a/docs/shared/reference/sitemap.md b/docs/shared/reference/sitemap.md index 4fda79785ab98..089bedec7ccea 100644 --- a/docs/shared/reference/sitemap.md +++ b/docs/shared/reference/sitemap.md @@ -224,6 +224,7 @@ - [workspace.json](/deprecated/workspace-json) - [As Provided vs. Derived](/deprecated/as-provided-vs-derived) - [Workspace Generators](/deprecated/workspace-generators) + - [Custom Task Runners](/deprecated/custom-task-runners) - [Workspace Executors](/deprecated/workspace-executors) - [runtimeCacheInputs](/deprecated/runtime-cache-inputs) - [cacheableOperations](/deprecated/cacheable-operations) From efa82000d89df54520f3e4c12c21652b2315c6b9 Mon Sep 17 00:00:00 2001 From: Isaac Mann Date: Thu, 19 Sep 2024 16:33:38 -0400 Subject: [PATCH 3/9] docs(core): placeholder links --- docs/shared/deprecated/custom-task-runners.md | 2 +- docs/shared/features/powerpack/custom-caching.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/shared/deprecated/custom-task-runners.md b/docs/shared/deprecated/custom-task-runners.md index 0336bd0b853ef..293a0d7148c54 100644 --- a/docs/shared/deprecated/custom-task-runners.md +++ b/docs/shared/deprecated/custom-task-runners.md @@ -8,5 +8,5 @@ As of Nx 20, custom task runners (defined via `tasksRunnerOptions`) and the `cac For most organizations, this feature is a net positive. If you are currently using a custom task runner, you are mostly likely using it to define your own custom [remote cache](/ci/features/remote-cache) storage location. You have several options moving forward: 1. Use [Nx Cloud](/nx-cloud) for your remote cache -2. Use an [Nx Powerpack](/powerpack) plugin to store your remote cache on an [AWS S3 bucket](/nx-api/powerpack-s3-cache) or a [network drive](/nx-api/powerpack-shared-fs-cache) +2. Use an [Nx Powerpack]() plugin to store your remote cache on an [AWS S3 bucket](/nx-api/powerpack-s3-cache) or a [network drive]() 3. Use the deprecated custom task runner feature until Nx 21 diff --git a/docs/shared/features/powerpack/custom-caching.md b/docs/shared/features/powerpack/custom-caching.md index 070b97a5415f5..6093058478746 100644 --- a/docs/shared/features/powerpack/custom-caching.md +++ b/docs/shared/features/powerpack/custom-caching.md @@ -2,7 +2,7 @@ The recommended way to enable the [remote cache]() is to use [Nx Replay]() and have Nx Cloud share the task cache across your organization. For those organizations that are unable to use Nx Cloud, Nx offers official plugins that are enabled by [Nx Powerpack]() to customize your remote cache location in a fast and secure manner. -In Nx 20, the local cache mechanism is getting faster and more secure by storing the cache in a database instead of directly on the file system. The new cache is faster because it avoids the unavoidably slow speed of interacting with the file system. The new cache is more secure because it eliminates the possibility that other processes with file system access could read or modify the cache. The [`@nx/powerpack-s3-cache`](/nx-api/powerpack-s3-cache) and [`@nx/powerpack-shared-fs-cache`](/nx-api/powerpack-shared-fs-cache) plugins enable you to leverage that speed and security with a custom remote cache storage location. +In Nx 20, the local cache mechanism is getting faster and more secure by storing the cache in a database instead of directly on the file system. The new cache is faster because it avoids the unavoidably slow speed of interacting with the file system. The new cache is more secure because it eliminates the possibility that other processes with file system access could read or modify the cache. The [`@nx/powerpack-s3-cache`](/nx-api/powerpack-s3-cache) and [`@nx/powerpack-shared-fs-cache`]() plugins enable you to leverage that speed and security with a custom remote cache storage location. {% callout type="note" title="Custom Task Runners are Deprecated in Nx 20" %} If you have a custom coded method for changing the remote cache location that uses either `tasksRunnerOptions` or `cacheDirectory`, you'll need to choose a migration path. Those properties are [deprecated in Nx 20](/deprecated/custom-task-runners) and will be removed in Nx 21. @@ -22,7 +22,7 @@ Read the individual plugin documentation for specific set up instructions. {% link-card title="AWS S3 Bucket Remote Cache" type="Nx Plugin" url="/nx-api/powerpack-s3-cache" icon="aws" /%} -{% link-card title="Shared Network Drive Remote Cache" type="Nx Plugin" url="/nx-api/powerpack-shared-fs-cache" icon="network" /%} +{% link-card title="Shared Network Drive Remote Cache" type="Nx Plugin" url="/nx-api/powerpack-s3-cache" icon="network" /%} {% /cards %} From 757ac4e35a7193ae53dd33fb7ae6bb2e71925484 Mon Sep 17 00:00:00 2001 From: Isaac Mann Date: Fri, 20 Sep 2024 09:17:05 -0400 Subject: [PATCH 4/9] docs(core): cards use nx-dev icons and hero icons --- .../external-generated/packages-metadata.json | 23 ++++- .../powerpack-s3-cache/documents/overview.md | 88 ++++++++++++++++++- .../powerpack-s3-cache/generators/init.json | 6 +- .../generators/init.json | 19 ++++ docs/generated/manifests/menus.json | 26 ++++++ docs/generated/manifests/nx-api.json | 24 ++++- .../features/powerpack/custom-caching.md | 4 +- docs/shared/reference/sitemap.md | 3 + .../src/lib/tags/cards.component.tsx | 16 +++- 9 files changed, 199 insertions(+), 10 deletions(-) create mode 100644 docs/external-generated/packages/powerpack-shared-fs-cache/generators/init.json diff --git a/docs/external-generated/packages-metadata.json b/docs/external-generated/packages-metadata.json index 5a3028a6fcdf4..229493aa5c791 100644 --- a/docs/external-generated/packages-metadata.json +++ b/docs/external-generated/packages-metadata.json @@ -97,7 +97,7 @@ "file": "external-generated/packages/powerpack-s3-cache/generators/init.json", "hidden": false, "name": "init", - "originalFilePath": "/libs/nx-packages/powerpack-s3-cache/src/generators/schema.json", + "originalFilePath": "/libs/nx-packages/powerpack-s3-cache/src/generators/init/schema.json", "path": "powerpack-s3-cache/generators/init", "type": "generator" } @@ -107,5 +107,26 @@ "packageName": "@nx/powerpack-s3-cache", "root": "/libs/nx-packages/powerpack-s3-cache", "source": "/libs/nx-packages/powerpack-s3-cache/src" + }, + { + "description": "A Nx Powerpack plugin for an Nx cache which is shared through the filesystem", + "documents": [], + "executors": [], + "generators": [ + { + "description": "Add the shared fs cache", + "file": "external-generated/packages/powerpack-shared-fs-cache/generators/init.json", + "hidden": false, + "name": "init", + "originalFilePath": "/libs/nx-packages/powerpack-shared-fs-cache/src/generators/init/schema.json", + "path": "powerpack-shared-fs-cache/generators/init", + "type": "generator" + } + ], + "githubRoot": "https://github.com/nrwl/nx/blob/master", + "name": "powerpack-shared-fs-cache", + "packageName": "@nx/powerpack-shared-fs-cache", + "root": "/libs/nx-packages/powerpack-shared-fs-cache", + "source": "/libs/nx-packages/powerpack-shared-fs-cache/src" } ] diff --git a/docs/external-generated/packages/powerpack-s3-cache/documents/overview.md b/docs/external-generated/packages/powerpack-s3-cache/documents/overview.md index 51c0779b647d0..80ba95ac9ac8c 100644 --- a/docs/external-generated/packages/powerpack-s3-cache/documents/overview.md +++ b/docs/external-generated/packages/powerpack-s3-cache/documents/overview.md @@ -1,6 +1,90 @@ --- title: Overview of the Nx powerpack-s3-cache Plugin -description: The Nx Plugin for esbuild contains executors and generators that support building applications using esbuild. This page also explains how to configure esbuild on your Nx workspace. +description: The powerpack-s3-cache Nx plugin enables you to use an AWS S3 bucket to host your remote cache instead of Nx Cloud --- -Powerpack s3-cache +{% callout title="This plugin requires an active Nx Powerpack license" %} +In order to use `@nx/powerpack-owners`, you need to have an active Powerpack license. If you don't have a license or it has expired, the syncing process will stop working and you'll need to manually maintain your CODEOWNERS file. +{% /callout %} + +## Setup + +### 1. Install the Package + +1. [Activate Powerpack](/recipes/installation/activate-powerpack) if you haven't already +2. Install the package + +```shell +nx add @nx/powerpack-owners +``` + +### 2. Authenticate with AWS + +There are four different ways to authenticate with AWS. They will be attempted in this order: + +1. Environment variables +2. INI config files +3. Single sign-on +4. `nx.json` settings + +#### Environment Variables + +[AWS provides environment variables](https://docs.aws.amazon.com/sdkref/latest/guide/environment-variables.html) that can be used to authenticate: + +| **Environment Variable** | **Description** | +| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AWS_ACCESS_KEY_ID` | The access key for your AWS account. | +| `AWS_SECRET_ACCESS_KEY` | The secret key for your AWS account. | +| `AWS_SESSION_TOKEN` | The session key for your AWS account. This is only needed when you are using temporary credentials. | +| `AWS_CREDENTIAL_EXPIRATION` | The expiration time of the credentials contained in the environment variables described above. This value must be in a format compatible with the [ISO-8601 standard](https://en.wikipedia.org/wiki/ISO_8601) and is only needed when you are using temporary credentials. | + +Both the `AWS_ACCESS_KEY_ID` and the `AWS_SECRET_ACCESS_KEY` environment variables are required to use the environment variable authentication method. + +#### INI Config Files + +AWS can read your authentication credentials from [shared INI config files](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html). The files are located at `~/.aws/credentials` and `~/.aws/config`. Both files are expected to be INI formatted with section names corresponding to profiles. Sections in the credentials file are treated as profile names, whereas profile sections in the config file must have the format of `[profile profile-name]`, except for the default profile. Profiles that appear in both files will not be merged, and the version that appears in the credentials file will be given precedence over the profile found in the config file. + +#### Single Sign-On + +Nx can read the active access token [created after running `aws sso login`](https://docs.aws.amazon.com/sdkref/latest/guide/understanding-sso.html) then request temporary AWS credentials. You can create the `AwsCredentialIdentityProvider` functions using the inline SSO parameters (`ssoStartUrl`, `ssoAccountId`, `ssoRegion`, `ssoRoleName`) or load them from [AWS SDKs and Tools shared configuration and credentials files](https://docs.aws.amazon.com/credref/latest/refdocs/creds-config-files.html). Profiles in the `credentials` file are given precedence over profiles in the `config` file. + +#### Credentials in `nx.json` File + +Storing your credentials in the `nx.json` file is the least secure of the 4 authentication options, since anyone with read access to your code base will have access to your AWS credentials. + +```jsonc {% fileName="nx.json" %} +{ + "s3": { + "ssoProfile": "default", + "accessKeyId": "MYACCESSKEYID", + "secretAccessKey": "MYSECRETACCESSKEY" + } +} +``` + +| **Property** | **Description** | +| ------------------- | ----------------------------------------------------------------------------- | +| **ssoProfile** | The name of the profile to use from your AWS CLI SSO Configuration (optional) | +| **endpoint** | The AWS endpoint URL (optional) | +| **accessKeyId** | AWS Access Key ID (optional) | +| **secretAccessKey** | AWS secret access key (optional) | + +### 3. Configure S3 Cache + +Regardless of how you manage your AWS authentication, you need to configure your Nx cache in the `nx.json` file. The `bucket` that you specify needs to already exist - Nx doesn't create it for you. + +```jsonc {% fileName="nx.json" %} +{ + "s3": { + "region": "us-east-1", + "bucket": "my-bucket", + "encryptionKey": "create-your-own-key" + } +} +``` + +| **Property** | **Description** | +| ----------------- | --------------------------------------------------------------------------------- | +| **region** | The id of the AWS region to use | +| **bucket** | The name of the AWS bucket to use | +| **encryptionKey** | Nx encryption key used to encrypt and decrypt artifacts from the cache (optional) | diff --git a/docs/external-generated/packages/powerpack-s3-cache/generators/init.json b/docs/external-generated/packages/powerpack-s3-cache/generators/init.json index 58af25a1ca404..c1a7e74820ac7 100644 --- a/docs/external-generated/packages/powerpack-s3-cache/generators/init.json +++ b/docs/external-generated/packages/powerpack-s3-cache/generators/init.json @@ -1,6 +1,6 @@ { "name": "init", - "factory": "./src/generators/generator", + "factory": "./src/generators/init/generator", "schema": { "$schema": "https://json-schema.org/schema", "$id": "Init", @@ -22,9 +22,9 @@ "presets": [] }, "description": "Initialize the S3 Cache", - "implementation": "/libs/nx-packages/powerpack-s3-cache/src/generators/generator.ts", + "implementation": "/libs/nx-packages/powerpack-s3-cache/src/generators/init/generator.ts", "aliases": [], "hidden": false, - "path": "/libs/nx-packages/powerpack-s3-cache/src/generators/schema.json", + "path": "/libs/nx-packages/powerpack-s3-cache/src/generators/init/schema.json", "type": "generator" } diff --git a/docs/external-generated/packages/powerpack-shared-fs-cache/generators/init.json b/docs/external-generated/packages/powerpack-shared-fs-cache/generators/init.json new file mode 100644 index 0000000000000..50924a5b91eab --- /dev/null +++ b/docs/external-generated/packages/powerpack-shared-fs-cache/generators/init.json @@ -0,0 +1,19 @@ +{ + "name": "init", + "factory": "./src/generators/init/generator", + "schema": { + "$schema": "https://json-schema.org/schema", + "$id": "Init", + "title": "", + "type": "object", + "properties": {}, + "required": [], + "presets": [] + }, + "description": "Add the shared fs cache", + "implementation": "/libs/nx-packages/powerpack-shared-fs-cache/src/generators/init/generator.ts", + "aliases": [], + "hidden": false, + "path": "/libs/nx-packages/powerpack-shared-fs-cache/src/generators/init/schema.json", + "type": "generator" +} diff --git a/docs/generated/manifests/menus.json b/docs/generated/manifests/menus.json index 9a998c6fdb681..387ad76cd1350 100644 --- a/docs/generated/manifests/menus.json +++ b/docs/generated/manifests/menus.json @@ -10665,6 +10665,32 @@ ], "isExternal": false, "disableCollapsible": false + }, + { + "id": "powerpack-shared-fs-cache", + "path": "/nx-api/powerpack-shared-fs-cache", + "name": "powerpack-shared-fs-cache", + "children": [ + { + "id": "generators", + "path": "/nx-api/powerpack-shared-fs-cache/generators", + "name": "generators", + "children": [ + { + "id": "init", + "path": "/nx-api/powerpack-shared-fs-cache/generators/init", + "name": "init", + "children": [], + "isExternal": false, + "disableCollapsible": false + } + ], + "isExternal": false, + "disableCollapsible": false + } + ], + "isExternal": false, + "disableCollapsible": false } ] } diff --git a/docs/generated/manifests/nx-api.json b/docs/generated/manifests/nx-api.json index 480b5daf5d4c0..7a1f7734021e4 100644 --- a/docs/generated/manifests/nx-api.json +++ b/docs/generated/manifests/nx-api.json @@ -3606,11 +3606,33 @@ "file": "external-generated/packages/powerpack-s3-cache/generators/init.json", "hidden": false, "name": "init", - "originalFilePath": "/libs/nx-packages/powerpack-s3-cache/src/generators/schema.json", + "originalFilePath": "/libs/nx-packages/powerpack-s3-cache/src/generators/init/schema.json", "path": "/nx-api/powerpack-s3-cache/generators/init", "type": "generator" } }, "path": "/nx-api/powerpack-s3-cache" + }, + "powerpack-shared-fs-cache": { + "githubRoot": "https://github.com/nrwl/nx/blob/master", + "name": "powerpack-shared-fs-cache", + "packageName": "@nx/powerpack-shared-fs-cache", + "description": "A Nx Powerpack plugin for an Nx cache which is shared through the filesystem", + "documents": {}, + "root": "/libs/nx-packages/powerpack-shared-fs-cache", + "source": "/libs/nx-packages/powerpack-shared-fs-cache/src", + "executors": {}, + "generators": { + "/nx-api/powerpack-shared-fs-cache/generators/init": { + "description": "Add the shared fs cache", + "file": "external-generated/packages/powerpack-shared-fs-cache/generators/init.json", + "hidden": false, + "name": "init", + "originalFilePath": "/libs/nx-packages/powerpack-shared-fs-cache/src/generators/init/schema.json", + "path": "/nx-api/powerpack-shared-fs-cache/generators/init", + "type": "generator" + } + }, + "path": "/nx-api/powerpack-shared-fs-cache" } } diff --git a/docs/shared/features/powerpack/custom-caching.md b/docs/shared/features/powerpack/custom-caching.md index 6093058478746..e9241770a05d8 100644 --- a/docs/shared/features/powerpack/custom-caching.md +++ b/docs/shared/features/powerpack/custom-caching.md @@ -20,9 +20,9 @@ Read the individual plugin documentation for specific set up instructions. {% cards cols="2" lgCols="2" mdCols="2" smCols="2" %} -{% link-card title="AWS S3 Bucket Remote Cache" type="Nx Plugin" url="/nx-api/powerpack-s3-cache" icon="aws" /%} +{% link-card title="AWS S3 Bucket Remote Cache" type="Nx Plugin" url="/nx-api/powerpack-s3-cache" icon="AwsIcon" /%} -{% link-card title="Shared Network Drive Remote Cache" type="Nx Plugin" url="/nx-api/powerpack-s3-cache" icon="network" /%} +{% link-card title="Shared Network Drive Remote Cache" type="Nx Plugin" url="/nx-api/powerpack-s3-cache" icon="ServerIcon" /%} {% /cards %} diff --git a/docs/shared/reference/sitemap.md b/docs/shared/reference/sitemap.md index 089bedec7ccea..bc14785166dd9 100644 --- a/docs/shared/reference/sitemap.md +++ b/docs/shared/reference/sitemap.md @@ -777,3 +777,6 @@ - [Overview](/nx-api/powerpack-s3-cache/documents/overview) - [generators](/nx-api/powerpack-s3-cache/generators) - [init](/nx-api/powerpack-s3-cache/generators/init) + - [powerpack-shared-fs-cache](/nx-api/powerpack-shared-fs-cache) + - [generators](/nx-api/powerpack-shared-fs-cache/generators) + - [init](/nx-api/powerpack-shared-fs-cache/generators/init) diff --git a/nx-dev/ui-markdoc/src/lib/tags/cards.component.tsx b/nx-dev/ui-markdoc/src/lib/tags/cards.component.tsx index 5f039b82acdb7..7f970820dcb6d 100644 --- a/nx-dev/ui-markdoc/src/lib/tags/cards.component.tsx +++ b/nx-dev/ui-markdoc/src/lib/tags/cards.component.tsx @@ -5,6 +5,8 @@ import { PlayCircleIcon, } from '@heroicons/react/24/outline'; import { Framework, frameworkIcons } from '@nx/graph/ui-icons'; +import * as nxDevIcons from '@nx/nx-dev/ui-icons'; +import * as heroIcons from '@heroicons/react/24/outline'; import { cx } from '@nx/nx-dev/ui-primitives'; import { ReactNode } from 'react'; @@ -99,6 +101,13 @@ export function Cards({ ); } +function callIfFunction(fn: any) { + if (typeof fn === 'function') { + return fn({}); + } + return fn; +} + export function LinkCard({ title, type, @@ -129,7 +138,12 @@ export function LinkCard({ } )} > - {icon && frameworkIcons[icon as Framework]?.image} + {icon && + (frameworkIcons[icon as Framework]?.image || + callIfFunction(nxDevIcons[icon as keyof typeof nxDevIcons]) || + callIfFunction( + (heroIcons[icon as keyof typeof heroIcons] as any).render + ))} )}
Date: Fri, 20 Sep 2024 14:13:09 -0400 Subject: [PATCH 5/9] docs(core): shared-fs plugin docs --- .../external-generated/packages-metadata.json | 14 ++++++- .../powerpack-s3-cache/documents/overview.md | 6 ++- .../documents/overview.md | 41 +++++++++++++++++++ docs/generated/manifests/menus.json | 17 ++++++++ docs/generated/manifests/nx-api.json | 14 ++++++- docs/map.json | 13 ++++++ docs/nx-cloud/concepts/cache-security.md | 2 +- docs/shared/deprecated/custom-task-runners.md | 8 ++-- .../features/powerpack/custom-caching.md | 10 ++--- docs/shared/guides/unknown-local-cache.md | 18 +------- .../powerpack-s3-cache-plugin.md | 6 ++- .../powerpack-shared-fs-cache-plugin.md | 41 +++++++++++++++++++ docs/shared/reference/sitemap.md | 2 + .../src/lib/tags/cards.component.tsx | 2 +- 14 files changed, 161 insertions(+), 33 deletions(-) create mode 100644 docs/external-generated/packages/powerpack-shared-fs-cache/documents/overview.md create mode 100644 docs/shared/packages/powerpack-shared-fs-cache/powerpack-shared-fs-cache-plugin.md diff --git a/docs/external-generated/packages-metadata.json b/docs/external-generated/packages-metadata.json index 229493aa5c791..55c2ebe029957 100644 --- a/docs/external-generated/packages-metadata.json +++ b/docs/external-generated/packages-metadata.json @@ -110,7 +110,19 @@ }, { "description": "A Nx Powerpack plugin for an Nx cache which is shared through the filesystem", - "documents": [], + "documents": [ + { + "id": "overview", + "name": "Overview", + "description": "A Nx Powerpack plugin for an Nx cache which is shared through the filesystem", + "file": "external-generated/packages/powerpack-shared-fs-cache/documents/overview", + "itemList": [], + "isExternal": false, + "path": "powerpack-shared-fs-cache/documents/overview", + "tags": [], + "originalFilePath": "shared/packages/powerpack-shared-fs-cache/powerpack-shared-fs-cache-plugin" + } + ], "executors": [], "generators": [ { diff --git a/docs/external-generated/packages/powerpack-s3-cache/documents/overview.md b/docs/external-generated/packages/powerpack-s3-cache/documents/overview.md index 80ba95ac9ac8c..517a6fa82d347 100644 --- a/docs/external-generated/packages/powerpack-s3-cache/documents/overview.md +++ b/docs/external-generated/packages/powerpack-s3-cache/documents/overview.md @@ -3,8 +3,10 @@ title: Overview of the Nx powerpack-s3-cache Plugin description: The powerpack-s3-cache Nx plugin enables you to use an AWS S3 bucket to host your remote cache instead of Nx Cloud --- +The `@nx/powerpack-s3-cache` plugin enables you to use an AWS S3 bucket instead of Nx Cloud to host your remote cache. + {% callout title="This plugin requires an active Nx Powerpack license" %} -In order to use `@nx/powerpack-owners`, you need to have an active Powerpack license. If you don't have a license or it has expired, the syncing process will stop working and you'll need to manually maintain your CODEOWNERS file. +In order to use `@nx/powerpack-s3-cache`, you need to have an active Powerpack license. If you don't have a license or it has expired, your cache will no longer be shared and each machine will use its local cache. {% /callout %} ## Setup @@ -15,7 +17,7 @@ In order to use `@nx/powerpack-owners`, you need to have an active Powerpack lic 2. Install the package ```shell -nx add @nx/powerpack-owners +nx add @nx/powerpack-s3-cache ``` ### 2. Authenticate with AWS diff --git a/docs/external-generated/packages/powerpack-shared-fs-cache/documents/overview.md b/docs/external-generated/packages/powerpack-shared-fs-cache/documents/overview.md new file mode 100644 index 0000000000000..2ab06fa8c8cfe --- /dev/null +++ b/docs/external-generated/packages/powerpack-shared-fs-cache/documents/overview.md @@ -0,0 +1,41 @@ +--- +title: Overview of the Nx powerpack-shared-fs-cache Plugin +description: The powerpack-shared-fs-cache Nx plugin enables you to use an shared file system directory instead of Nx Cloud to host your remote cache +--- + +The `@nx/powerpack-shared-fs-cache` plugin enables you to use an shared file system directory instead of Nx Cloud to host your remote cache. You are responsible for the sharing mechanism for the directory, but the plugin ensures that Nx correctly associates task metadata with the file artifacts. + +{% callout type="warning" title="Potential Cache Poisoning" %} +Using a shared file system folder for the remote cache opens you up to the possibility of cache poisoning. To avoid this, use [Nx Replay](/ci/features/remote-cache) or share your cache with an AWS S3 bucket using [`@nx/powerpack-s3-cache`](/nx-api/powerpack-s3-cache). +{% /callout %} + +{% callout title="This plugin requires an active Nx Powerpack license" %} +In order to use `@nx/powerpack-shared-fs-cache`, you need to have an active Powerpack license. If you don't have a license or it has expired, your cache will no longer be shared and each machine will use its local cache. +{% /callout %} + +## Setup + +### 1. Install the Package + +1. [Activate Powerpack](/recipes/installation/activate-powerpack) if you haven't already +2. Install the package + +```shell +nx add @nx/powerpack-shared-fs-cache +``` + +### 2. Configure the Cache Directory + +The `@nx/powerpack-shared-fs-cache` plugin treats your local cache directory as if it is also a remote cache directory. The local cache directory can be set using `cacheDirectory` in the `nx.json` file or the `NX_CACHE_DIRECTORY` environment variable. The default local cache directory is `.nx/cache` + +### 3. Share the Cache Directory + +The `@nx/powerpack-shared-fs-cache` plugin does not actually share the cache directory across your organization. If you want that functionality, use [Nx Replay](/ci/features/remote-cache) instead. Here are a few ways you could manually share the cache directory. + +#### Restore an Nx Cache Locally from a Remote Cache provided by a CI Provider + +Many CI providers allow users to restore files and directories from their cache. You can restore this folder on subsequent CI runs or use an API to download that cache folder to local developer machines. The mechanism for doing this will differ based on your CI provider. + +#### Share an Nx Cache With a Network Drive + +It is also possible to share an Nx Cache by storing it on a mounted network drive. You are responsible for ensuring that CI machines and local developer machines have access to the network drive in a consistent way. If the network drive will be mounted on different paths, you can overwrite the default `cacheDirectory` with machine specific `NX_CACHE_DIRECTORY` environment variables. diff --git a/docs/generated/manifests/menus.json b/docs/generated/manifests/menus.json index 387ad76cd1350..33e684f998356 100644 --- a/docs/generated/manifests/menus.json +++ b/docs/generated/manifests/menus.json @@ -10671,6 +10671,23 @@ "path": "/nx-api/powerpack-shared-fs-cache", "name": "powerpack-shared-fs-cache", "children": [ + { + "id": "documents", + "path": "/nx-api/powerpack-shared-fs-cache/documents", + "name": "documents", + "children": [ + { + "name": "Overview", + "path": "/nx-api/powerpack-shared-fs-cache/documents/overview", + "id": "overview", + "isExternal": false, + "children": [], + "disableCollapsible": false + } + ], + "isExternal": false, + "disableCollapsible": false + }, { "id": "generators", "path": "/nx-api/powerpack-shared-fs-cache/generators", diff --git a/docs/generated/manifests/nx-api.json b/docs/generated/manifests/nx-api.json index 7a1f7734021e4..d44075c6a0d94 100644 --- a/docs/generated/manifests/nx-api.json +++ b/docs/generated/manifests/nx-api.json @@ -3618,7 +3618,19 @@ "name": "powerpack-shared-fs-cache", "packageName": "@nx/powerpack-shared-fs-cache", "description": "A Nx Powerpack plugin for an Nx cache which is shared through the filesystem", - "documents": {}, + "documents": { + "/nx-api/powerpack-shared-fs-cache/documents/overview": { + "id": "overview", + "name": "Overview", + "description": "A Nx Powerpack plugin for an Nx cache which is shared through the filesystem", + "file": "external-generated/packages/powerpack-shared-fs-cache/documents/overview", + "itemList": [], + "isExternal": false, + "path": "/nx-api/powerpack-shared-fs-cache/documents/overview", + "tags": [], + "originalFilePath": "shared/packages/powerpack-shared-fs-cache/powerpack-shared-fs-cache-plugin" + } + }, "root": "/libs/nx-packages/powerpack-shared-fs-cache", "source": "/libs/nx-packages/powerpack-shared-fs-cache/src", "executors": {}, diff --git a/docs/map.json b/docs/map.json index a73cb84ad906f..323512dc95466 100644 --- a/docs/map.json +++ b/docs/map.json @@ -2636,6 +2636,19 @@ } ] }, + { + "name": "powerpack-shared-fs-cache", + "id": "powerpack-shared-fs-cache", + "description": "powerpack-shared-fs-cache package.", + "itemList": [ + { + "name": "Overview", + "id": "overview", + "path": "/nx-api/powerpack-shared-fs-cache", + "file": "shared/packages/powerpack-shared-fs-cache/powerpack-shared-fs-cache-plugin" + } + ] + }, { "name": "gradle", "id": "gradle", diff --git a/docs/nx-cloud/concepts/cache-security.md b/docs/nx-cloud/concepts/cache-security.md index 3260465f8af62..616d9b1672b3d 100644 --- a/docs/nx-cloud/concepts/cache-security.md +++ b/docs/nx-cloud/concepts/cache-security.md @@ -46,7 +46,7 @@ In order to guarantee that cache poisoning will never affect your end users, [sk ### Do Not Manually Share Your Local Cache -Nx implicitly trusts the local cache which is stored by default in the `.nx/cache` folder. You can change the location of that folder in the `nx.json` file, so it could be tempting to place it on a network drive and easily share your cache with everyone on the company network. However, by doing this you've voided the guarantee of immutability from your cache. If someone has direct access to the cached files, they could directly poison the cache. Nx will automatically detect if a cache entry has been created in your local cache using a different machine and warn you with an [Unknown Local Cache Error](/troubleshooting/unknown-local-cache). Instead, use Nx Cloud [remote caching](/ci/features/remote-cache). +Nx implicitly trusts the local cache which is stored by default in the `.nx/cache` folder. You can change the location of that folder in the `nx.json` file, so it could be tempting to place it on a network drive and easily share your cache with everyone on the company network. However, by doing this you've voided the guarantee of immutability from your cache. If someone has direct access to the cached files, they could directly poison the cache. Nx will automatically detect if a cache entry has been created in your local cache using a different machine and warn you with an [Unknown Local Cache Error](/troubleshooting/unknown-local-cache). Instead, use Nx Cloud [remote caching](/ci/features/remote-cache). If you want share your local cache anyway, you can [activate Nx Powerpack](/recipes/installation/activate-powerpack) and use the [`@nx/powerpack-shared-fs-cache`](/nx-api/powerpack-shared-fs-cache) plugin. ### Configure End to End Encryption diff --git a/docs/shared/deprecated/custom-task-runners.md b/docs/shared/deprecated/custom-task-runners.md index 293a0d7148c54..1f8a5b61fe2e2 100644 --- a/docs/shared/deprecated/custom-task-runners.md +++ b/docs/shared/deprecated/custom-task-runners.md @@ -1,12 +1,12 @@ -# tasksRunnerOptions and cacheDirectory +# tasksRunnerOptions -As of Nx 20, custom task runners (defined via `tasksRunnerOptions`) and the `cacheDirectory` property in `nx.json` are deprecated. They will cease to function in Nx 21. In Nx 20, the local cache is stored in a database, rather than using the file system. This has two benefits: +As of Nx 20, the `tasksRunnerOptions` property in `nx.json` is deprecated. This property was used to register custom task runners. `tasksRunnerOptions` and custom task runners will cease to function in Nx 21. In Nx 20, the local cache metadata and project graph are stored in a database, rather than using the file system. (Cache artifacts are still stored on the file system.) This has two benefits: 1. Cache reads and writes are faster. 2. The local cache is more secure since other processes with access to the file system can no longer read or modify the cache. -For most organizations, this feature is a net positive. If you are currently using a custom task runner, you are mostly likely using it to define your own custom [remote cache](/ci/features/remote-cache) storage location. You have several options moving forward: +For most organizations, this feature is a net positive. If you are currently using a custom task runner, you are most likely using it to define your own custom [remote cache](/ci/features/remote-cache) storage location. You have several options moving forward: 1. Use [Nx Cloud](/nx-cloud) for your remote cache -2. Use an [Nx Powerpack]() plugin to store your remote cache on an [AWS S3 bucket](/nx-api/powerpack-s3-cache) or a [network drive]() +2. Use an [Nx Powerpack]() plugin to store your remote cache on an [AWS S3 bucket](/nx-api/powerpack-s3-cache) or a [network drive](/nx-api/powerpack-shared-fs-cache) 3. Use the deprecated custom task runner feature until Nx 21 diff --git a/docs/shared/features/powerpack/custom-caching.md b/docs/shared/features/powerpack/custom-caching.md index e9241770a05d8..81823909a0e93 100644 --- a/docs/shared/features/powerpack/custom-caching.md +++ b/docs/shared/features/powerpack/custom-caching.md @@ -1,18 +1,18 @@ # Change the Remote Cache Storage Location -The recommended way to enable the [remote cache]() is to use [Nx Replay]() and have Nx Cloud share the task cache across your organization. For those organizations that are unable to use Nx Cloud, Nx offers official plugins that are enabled by [Nx Powerpack]() to customize your remote cache location in a fast and secure manner. +The recommended way to enable the [remote cache](/ci/features/remote-cache) is to use Nx Replay and have Nx Cloud share the task cache across your organization. For those organizations that are unable to use Nx Cloud, Nx offers official plugins that are enabled by [Nx Powerpack]() to customize your remote cache location in a fast and secure manner. -In Nx 20, the local cache mechanism is getting faster and more secure by storing the cache in a database instead of directly on the file system. The new cache is faster because it avoids the unavoidably slow speed of interacting with the file system. The new cache is more secure because it eliminates the possibility that other processes with file system access could read or modify the cache. The [`@nx/powerpack-s3-cache`](/nx-api/powerpack-s3-cache) and [`@nx/powerpack-shared-fs-cache`]() plugins enable you to leverage that speed and security with a custom remote cache storage location. +In Nx 20, the _local_ cache mechanism is getting faster and more secure by storing the cached metadata and project graph in a database instead of directly on the file system. The new cache is faster because it limits the fundamentally slow speed of interacting with the file system. The new cache is more secure because it reduces the amount of information that other processes with file system access could read or modify in the local cache directory. The [`@nx/powerpack-s3-cache`](/nx-api/powerpack-s3-cache) and [`@nx/powerpack-shared-fs-cache`](/nx-api/powerpack-shared-fs-cache) plugins enable you to leverage that speed and security with a custom _remote_ cache storage location. {% callout type="note" title="Custom Task Runners are Deprecated in Nx 20" %} -If you have a custom coded method for changing the remote cache location that uses either `tasksRunnerOptions` or `cacheDirectory`, you'll need to choose a migration path. Those properties are [deprecated in Nx 20](/deprecated/custom-task-runners) and will be removed in Nx 21. +If you have a custom coded method for changing the remote cache location that uses `tasksRunnerOptions`, you'll need to choose a migration path. Those properties are [deprecated in Nx 20](/deprecated/custom-task-runners) and will be removed in Nx 21. {% /callout %} ## Custom Remote Cache Storage Plugins Require Nx Powerpack The `@nx/powerpack-s3-cache` and `@nx/powerpack-shared-fs-cache` plugins require an Nx Powerpack license to function. [Activating Powerpack](/recipes/installation/activate-powerpack) is a simple process. -{% call-to-action title="Buy a Powerpack License" icon="nx" description="Unlock all the features of Nx" url="https://nx.app/nx-powerpack/purchase" /%} +{% call-to-action title="Buy a Powerpack License" icon="nx" description="Unlock all the features of the Nx CLI" url="https://nx.app/nx-powerpack/purchase" /%} ## Choose Your Storage Solution @@ -28,6 +28,6 @@ Read the individual plugin documentation for specific set up instructions. ## Switch to Nx Cloud -These custom remote cache storage solutions only provide the remote cache functionality of Nx Cloud. If you want to leverage [distributed task execution](), [re-running flaky tasks]() or [automatically splitting tasks](), you'll need to [connect to Nx Cloud]() and use Nx Cloud's remote cache solution instead. +These custom remote cache storage solutions only provide the remote cache functionality of Nx Cloud. If you want to leverage [distributed task execution](/ci/features/distribute-task-execution), [re-running flaky tasks](/ci/features/flaky-tasks) or [automatically splitting tasks](/ci/features/split-e2e-tasks), you'll need to [connect to Nx Cloud](/ci/intro/connect-to-nx-cloud) and use Nx Cloud's remote cache solution instead. {% call-to-action title="Connect to Nx Cloud" icon="nxcloud" description="Enable task distribution and Atomizer" url="/ci/intro/connect-to-nx-cloud" /%} diff --git a/docs/shared/guides/unknown-local-cache.md b/docs/shared/guides/unknown-local-cache.md index 0d12f24890334..6d980c020119a 100644 --- a/docs/shared/guides/unknown-local-cache.md +++ b/docs/shared/guides/unknown-local-cache.md @@ -46,25 +46,11 @@ access to all the previously created Nx cache artifacts. Hence, it is plausible single task hash - to be accessed without leaving any trace. This is feasible due to the network drive's capability to allow overwrites. -Instead of sharing the network drive, we highly recommend you to implement the `RemoteCache` interface. - -## Implementing Remote Cache Interface - -This is the interface: - -```typescript -interface RemoteCache { - retrieve(hash: string, cachePath: string); - - store(hash: string, cachePath: string); -} -``` - -> You will need to wrap the default tasks runner to provide the remote cache implementation. +If you decide to use a shared network drive for your remote cache anyway, [activate powerpack](/powerpack) and use the [`@nx/powerpack-shared-fs-cache`](/nx-api/powerpack-shared-fs-cache) plugin to ensure that the task metadata and project graph information is correctly associated with the file artifacts. ## How Nx Cloud Makes Sure Sharing Cache is Safe -The Nx Cloud runner provides an implementation of `RemoteCache` which does the following things making sharing the cache safe: +The Nx Cloud runner does the following things to make sharing the cache safe: 1. **Immutable Artifacts:** Nx Cloud allows you to create and store new artifacts without the ability to override the existing ones. This prevents any possibility of poisoning an existing artifact. This is achieved by managing the diff --git a/docs/shared/packages/powerpack-s3-cache/powerpack-s3-cache-plugin.md b/docs/shared/packages/powerpack-s3-cache/powerpack-s3-cache-plugin.md index 80ba95ac9ac8c..517a6fa82d347 100644 --- a/docs/shared/packages/powerpack-s3-cache/powerpack-s3-cache-plugin.md +++ b/docs/shared/packages/powerpack-s3-cache/powerpack-s3-cache-plugin.md @@ -3,8 +3,10 @@ title: Overview of the Nx powerpack-s3-cache Plugin description: The powerpack-s3-cache Nx plugin enables you to use an AWS S3 bucket to host your remote cache instead of Nx Cloud --- +The `@nx/powerpack-s3-cache` plugin enables you to use an AWS S3 bucket instead of Nx Cloud to host your remote cache. + {% callout title="This plugin requires an active Nx Powerpack license" %} -In order to use `@nx/powerpack-owners`, you need to have an active Powerpack license. If you don't have a license or it has expired, the syncing process will stop working and you'll need to manually maintain your CODEOWNERS file. +In order to use `@nx/powerpack-s3-cache`, you need to have an active Powerpack license. If you don't have a license or it has expired, your cache will no longer be shared and each machine will use its local cache. {% /callout %} ## Setup @@ -15,7 +17,7 @@ In order to use `@nx/powerpack-owners`, you need to have an active Powerpack lic 2. Install the package ```shell -nx add @nx/powerpack-owners +nx add @nx/powerpack-s3-cache ``` ### 2. Authenticate with AWS diff --git a/docs/shared/packages/powerpack-shared-fs-cache/powerpack-shared-fs-cache-plugin.md b/docs/shared/packages/powerpack-shared-fs-cache/powerpack-shared-fs-cache-plugin.md new file mode 100644 index 0000000000000..2ab06fa8c8cfe --- /dev/null +++ b/docs/shared/packages/powerpack-shared-fs-cache/powerpack-shared-fs-cache-plugin.md @@ -0,0 +1,41 @@ +--- +title: Overview of the Nx powerpack-shared-fs-cache Plugin +description: The powerpack-shared-fs-cache Nx plugin enables you to use an shared file system directory instead of Nx Cloud to host your remote cache +--- + +The `@nx/powerpack-shared-fs-cache` plugin enables you to use an shared file system directory instead of Nx Cloud to host your remote cache. You are responsible for the sharing mechanism for the directory, but the plugin ensures that Nx correctly associates task metadata with the file artifacts. + +{% callout type="warning" title="Potential Cache Poisoning" %} +Using a shared file system folder for the remote cache opens you up to the possibility of cache poisoning. To avoid this, use [Nx Replay](/ci/features/remote-cache) or share your cache with an AWS S3 bucket using [`@nx/powerpack-s3-cache`](/nx-api/powerpack-s3-cache). +{% /callout %} + +{% callout title="This plugin requires an active Nx Powerpack license" %} +In order to use `@nx/powerpack-shared-fs-cache`, you need to have an active Powerpack license. If you don't have a license or it has expired, your cache will no longer be shared and each machine will use its local cache. +{% /callout %} + +## Setup + +### 1. Install the Package + +1. [Activate Powerpack](/recipes/installation/activate-powerpack) if you haven't already +2. Install the package + +```shell +nx add @nx/powerpack-shared-fs-cache +``` + +### 2. Configure the Cache Directory + +The `@nx/powerpack-shared-fs-cache` plugin treats your local cache directory as if it is also a remote cache directory. The local cache directory can be set using `cacheDirectory` in the `nx.json` file or the `NX_CACHE_DIRECTORY` environment variable. The default local cache directory is `.nx/cache` + +### 3. Share the Cache Directory + +The `@nx/powerpack-shared-fs-cache` plugin does not actually share the cache directory across your organization. If you want that functionality, use [Nx Replay](/ci/features/remote-cache) instead. Here are a few ways you could manually share the cache directory. + +#### Restore an Nx Cache Locally from a Remote Cache provided by a CI Provider + +Many CI providers allow users to restore files and directories from their cache. You can restore this folder on subsequent CI runs or use an API to download that cache folder to local developer machines. The mechanism for doing this will differ based on your CI provider. + +#### Share an Nx Cache With a Network Drive + +It is also possible to share an Nx Cache by storing it on a mounted network drive. You are responsible for ensuring that CI machines and local developer machines have access to the network drive in a consistent way. If the network drive will be mounted on different paths, you can overwrite the default `cacheDirectory` with machine specific `NX_CACHE_DIRECTORY` environment variables. diff --git a/docs/shared/reference/sitemap.md b/docs/shared/reference/sitemap.md index bc14785166dd9..8847d47e0127f 100644 --- a/docs/shared/reference/sitemap.md +++ b/docs/shared/reference/sitemap.md @@ -778,5 +778,7 @@ - [generators](/nx-api/powerpack-s3-cache/generators) - [init](/nx-api/powerpack-s3-cache/generators/init) - [powerpack-shared-fs-cache](/nx-api/powerpack-shared-fs-cache) + - [documents](/nx-api/powerpack-shared-fs-cache/documents) + - [Overview](/nx-api/powerpack-shared-fs-cache/documents/overview) - [generators](/nx-api/powerpack-shared-fs-cache/generators) - [init](/nx-api/powerpack-shared-fs-cache/generators/init) diff --git a/nx-dev/ui-markdoc/src/lib/tags/cards.component.tsx b/nx-dev/ui-markdoc/src/lib/tags/cards.component.tsx index 7f970820dcb6d..d083bf5a883a2 100644 --- a/nx-dev/ui-markdoc/src/lib/tags/cards.component.tsx +++ b/nx-dev/ui-markdoc/src/lib/tags/cards.component.tsx @@ -142,7 +142,7 @@ export function LinkCard({ (frameworkIcons[icon as Framework]?.image || callIfFunction(nxDevIcons[icon as keyof typeof nxDevIcons]) || callIfFunction( - (heroIcons[icon as keyof typeof heroIcons] as any).render + (heroIcons[icon as keyof typeof heroIcons] as any)?.render ))}
)} From 7b71db026a8b487982b1a793ea20319f162e404e Mon Sep 17 00:00:00 2001 From: Isaac Mann Date: Fri, 20 Sep 2024 15:46:55 -0400 Subject: [PATCH 6/9] docs(core): fix link --- docs/shared/guides/unknown-local-cache.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/shared/guides/unknown-local-cache.md b/docs/shared/guides/unknown-local-cache.md index 6d980c020119a..d6890bf3f0ed1 100644 --- a/docs/shared/guides/unknown-local-cache.md +++ b/docs/shared/guides/unknown-local-cache.md @@ -46,7 +46,7 @@ access to all the previously created Nx cache artifacts. Hence, it is plausible single task hash - to be accessed without leaving any trace. This is feasible due to the network drive's capability to allow overwrites. -If you decide to use a shared network drive for your remote cache anyway, [activate powerpack](/powerpack) and use the [`@nx/powerpack-shared-fs-cache`](/nx-api/powerpack-shared-fs-cache) plugin to ensure that the task metadata and project graph information is correctly associated with the file artifacts. +If you decide to use a shared network drive for your remote cache anyway, [activate powerpack](/recipes/installation/activate-powerpack) and use the [`@nx/powerpack-shared-fs-cache`](/nx-api/powerpack-shared-fs-cache) plugin to ensure that the task metadata and project graph information is correctly associated with the file artifacts. ## How Nx Cloud Makes Sure Sharing Cache is Safe From 9c9d744c8bedc077b413d51b58faf887ca40c600 Mon Sep 17 00:00:00 2001 From: Isaac Mann Date: Mon, 23 Sep 2024 15:40:22 -0400 Subject: [PATCH 7/9] docs(core): updates from review --- .../documents/overview.md | 12 ++--------- docs/generated/manifests/menus.json | 6 +++--- docs/generated/manifests/nx.json | 6 +++--- docs/generated/manifests/tags.json | 2 +- docs/map.json | 2 +- .../features/powerpack/custom-caching.md | 14 ++++++------- docs/shared/guides/unknown-local-cache.md | 17 ++++++++++----- .../powerpack-shared-fs-cache-plugin.md | 12 ++--------- .../running-tasks/change-cache-location.md | 21 ------------------- docs/shared/reference/sitemap.md | 2 +- 10 files changed, 32 insertions(+), 62 deletions(-) diff --git a/docs/external-generated/packages/powerpack-shared-fs-cache/documents/overview.md b/docs/external-generated/packages/powerpack-shared-fs-cache/documents/overview.md index 2ab06fa8c8cfe..b71e355115982 100644 --- a/docs/external-generated/packages/powerpack-shared-fs-cache/documents/overview.md +++ b/docs/external-generated/packages/powerpack-shared-fs-cache/documents/overview.md @@ -6,7 +6,7 @@ description: The powerpack-shared-fs-cache Nx plugin enables you to use an share The `@nx/powerpack-shared-fs-cache` plugin enables you to use an shared file system directory instead of Nx Cloud to host your remote cache. You are responsible for the sharing mechanism for the directory, but the plugin ensures that Nx correctly associates task metadata with the file artifacts. {% callout type="warning" title="Potential Cache Poisoning" %} -Using a shared file system folder for the remote cache opens you up to the possibility of cache poisoning. To avoid this, use [Nx Replay](/ci/features/remote-cache) or share your cache with an AWS S3 bucket using [`@nx/powerpack-s3-cache`](/nx-api/powerpack-s3-cache). +Using a shared file system folder for the remote cache opens you up to the possibility of [cache poisoning](/troubleshooting/unknown-local-cache). To avoid this, use [Nx Replay](/ci/features/remote-cache) or share your cache with an AWS S3 bucket using [`@nx/powerpack-s3-cache`](/nx-api/powerpack-s3-cache). {% /callout %} {% callout title="This plugin requires an active Nx Powerpack license" %} @@ -30,12 +30,4 @@ The `@nx/powerpack-shared-fs-cache` plugin treats your local cache directory as ### 3. Share the Cache Directory -The `@nx/powerpack-shared-fs-cache` plugin does not actually share the cache directory across your organization. If you want that functionality, use [Nx Replay](/ci/features/remote-cache) instead. Here are a few ways you could manually share the cache directory. - -#### Restore an Nx Cache Locally from a Remote Cache provided by a CI Provider - -Many CI providers allow users to restore files and directories from their cache. You can restore this folder on subsequent CI runs or use an API to download that cache folder to local developer machines. The mechanism for doing this will differ based on your CI provider. - -#### Share an Nx Cache With a Network Drive - -It is also possible to share an Nx Cache by storing it on a mounted network drive. You are responsible for ensuring that CI machines and local developer machines have access to the network drive in a consistent way. If the network drive will be mounted on different paths, you can overwrite the default `cacheDirectory` with machine specific `NX_CACHE_DIRECTORY` environment variables. +The `@nx/powerpack-shared-fs-cache` plugin does not actually share the cache directory across your organization. If you want that functionality, use [Nx Replay](/ci/features/remote-cache) instead. Your shared file system directory might be a directory that is saved and restored by a CI provider or it could be a shared network drive. diff --git a/docs/generated/manifests/menus.json b/docs/generated/manifests/menus.json index 33e684f998356..f7eafc2ed49f4 100644 --- a/docs/generated/manifests/menus.json +++ b/docs/generated/manifests/menus.json @@ -346,7 +346,7 @@ "disableCollapsible": false }, { - "name": "Change the Remote Cache Storage Location", + "name": "Self-Host the Remote Cache", "path": "/features/powerpack/custom-caching", "id": "custom-caching", "isExternal": false, @@ -495,7 +495,7 @@ "disableCollapsible": false }, { - "name": "Change the Remote Cache Storage Location", + "name": "Self-Host the Remote Cache", "path": "/features/powerpack/custom-caching", "id": "custom-caching", "isExternal": false, @@ -522,7 +522,7 @@ "disableCollapsible": false }, { - "name": "Change the Remote Cache Storage Location", + "name": "Self-Host the Remote Cache", "path": "/features/powerpack/custom-caching", "id": "custom-caching", "isExternal": false, diff --git a/docs/generated/manifests/nx.json b/docs/generated/manifests/nx.json index 0da64f8865203..9e0fd96b60b24 100644 --- a/docs/generated/manifests/nx.json +++ b/docs/generated/manifests/nx.json @@ -469,7 +469,7 @@ }, { "id": "custom-caching", - "name": "Change the Remote Cache Storage Location", + "name": "Self-Host the Remote Cache", "description": "Custom Caching", "mediaImage": "", "file": "shared/features/powerpack/custom-caching", @@ -674,7 +674,7 @@ }, { "id": "custom-caching", - "name": "Change the Remote Cache Storage Location", + "name": "Self-Host the Remote Cache", "description": "Custom Caching", "mediaImage": "", "file": "shared/features/powerpack/custom-caching", @@ -712,7 +712,7 @@ }, "/features/powerpack/custom-caching": { "id": "custom-caching", - "name": "Change the Remote Cache Storage Location", + "name": "Self-Host the Remote Cache", "description": "Custom Caching", "mediaImage": "", "file": "shared/features/powerpack/custom-caching", diff --git a/docs/generated/manifests/tags.json b/docs/generated/manifests/tags.json index d89ae8cdb2689..cd7abecdb7ed0 100644 --- a/docs/generated/manifests/tags.json +++ b/docs/generated/manifests/tags.json @@ -598,7 +598,7 @@ "description": "Custom Caching", "file": "shared/features/powerpack/custom-caching", "id": "custom-caching", - "name": "Change the Remote Cache Storage Location", + "name": "Self-Host the Remote Cache", "path": "/features/powerpack/custom-caching" } ], diff --git a/docs/map.json b/docs/map.json index 323512dc95466..04c7f6989a8c1 100644 --- a/docs/map.json +++ b/docs/map.json @@ -151,7 +151,7 @@ "file": "shared/features/powerpack/owners" }, { - "name": "Change the Remote Cache Storage Location", + "name": "Self-Host the Remote Cache", "description": "Custom Caching", "id": "custom-caching", "tags": ["custom-caching"], diff --git a/docs/shared/features/powerpack/custom-caching.md b/docs/shared/features/powerpack/custom-caching.md index 81823909a0e93..5b3db9624e4f2 100644 --- a/docs/shared/features/powerpack/custom-caching.md +++ b/docs/shared/features/powerpack/custom-caching.md @@ -1,14 +1,14 @@ -# Change the Remote Cache Storage Location +# Self-Host the Remote Cache -The recommended way to enable the [remote cache](/ci/features/remote-cache) is to use Nx Replay and have Nx Cloud share the task cache across your organization. For those organizations that are unable to use Nx Cloud, Nx offers official plugins that are enabled by [Nx Powerpack]() to customize your remote cache location in a fast and secure manner. +The recommended way to enable the [remote cache](/ci/features/remote-cache) is to use Nx Replay and have Nx Cloud share the task cache across your organization. For those organizations that are unable to use Nx Cloud, Nx offers official plugins that are enabled by [Nx Powerpack]() to self-host the remote cache in a fast and secure manner. The recommended ways to host the remote cache are, in order of preference: -In Nx 20, the _local_ cache mechanism is getting faster and more secure by storing the cached metadata and project graph in a database instead of directly on the file system. The new cache is faster because it limits the fundamentally slow speed of interacting with the file system. The new cache is more secure because it reduces the amount of information that other processes with file system access could read or modify in the local cache directory. The [`@nx/powerpack-s3-cache`](/nx-api/powerpack-s3-cache) and [`@nx/powerpack-shared-fs-cache`](/nx-api/powerpack-shared-fs-cache) plugins enable you to leverage that speed and security with a custom _remote_ cache storage location. +1. [Nx Replay](/ci/features/remote-cache): Cache is hosted on Nx Cloud servers or on-premise with an [Nx Enterprise](/enterprise) contract +2. [@nx/powerpack-s3-cache](/nx-api/powerpack-s3-cache): Cache is on a self-hosted, fully secure AWS S3 bucket +3. [@nx/powerpack-shared-fs-cache(/nx-api/powerpack-s3-cache): Cache is self-hosted and self-secured on a shared file system location -{% callout type="note" title="Custom Task Runners are Deprecated in Nx 20" %} -If you have a custom coded method for changing the remote cache location that uses `tasksRunnerOptions`, you'll need to choose a migration path. Those properties are [deprecated in Nx 20](/deprecated/custom-task-runners) and will be removed in Nx 21. -{% /callout %} +The options range from fully opting in to Nx's management of the remote cache to fully managing the configuration and security of your own remote cache. -## Custom Remote Cache Storage Plugins Require Nx Powerpack +## Self-Hosted Remote Cache Plugins Require Nx Powerpack The `@nx/powerpack-s3-cache` and `@nx/powerpack-shared-fs-cache` plugins require an Nx Powerpack license to function. [Activating Powerpack](/recipes/installation/activate-powerpack) is a simple process. diff --git a/docs/shared/guides/unknown-local-cache.md b/docs/shared/guides/unknown-local-cache.md index d6890bf3f0ed1..34b7b8d7ce7e0 100644 --- a/docs/shared/guides/unknown-local-cache.md +++ b/docs/shared/guides/unknown-local-cache.md @@ -46,11 +46,9 @@ access to all the previously created Nx cache artifacts. Hence, it is plausible single task hash - to be accessed without leaving any trace. This is feasible due to the network drive's capability to allow overwrites. -If you decide to use a shared network drive for your remote cache anyway, [activate powerpack](/recipes/installation/activate-powerpack) and use the [`@nx/powerpack-shared-fs-cache`](/nx-api/powerpack-shared-fs-cache) plugin to ensure that the task metadata and project graph information is correctly associated with the file artifacts. +## How Nx Replay Makes Sure Sharing Cache is Safe -## How Nx Cloud Makes Sure Sharing Cache is Safe - -The Nx Cloud runner does the following things to make sharing the cache safe: +[Nx Replay](/ci/features/remote-cache), the Nx Cloud hosted remote cache, does the following things to make sharing the cache safe: 1. **Immutable Artifacts:** Nx Cloud allows you to create and store new artifacts without the ability to override the existing ones. This prevents any possibility of poisoning an existing artifact. This is achieved by managing the @@ -67,6 +65,15 @@ The Nx Cloud runner does the following things to make sharing the cache safe: an access token gets compromised it can be easily removed, in turn deleting all the cache artifacts that were created using it. -Nx Cloud is not the only remote cache you can use. If you are using a different remote cache or using your +Nx Replay is not the only remote cache you can use. If you are using a different remote cache or using your own implementation, we would highly recommend ensuring that the same safety mechanisms as Nx Cloud have been put in place. + +## Self-Hosted Remote Cache + +If you can't use Nx Replay, Nx provides plugins that enable you to [self-host the remote cache](/features/powerpack/custom-caching). These plugins are available as part of the [Nx Powerpack](), which you can unlock by [activating your license](/recipes/installation/activate-powerpack). There are plugins to self-host your remote cache in the following locations: + +- [AWS S3 Bucket](/nx-api/powerpack-s3-cache) +- [Shared File System](/nx-api/powerpack-shared-fs-cache) + +These plugins will ensure that the task metadata and project graph information are correctly associated with the file artifacts in your cache. diff --git a/docs/shared/packages/powerpack-shared-fs-cache/powerpack-shared-fs-cache-plugin.md b/docs/shared/packages/powerpack-shared-fs-cache/powerpack-shared-fs-cache-plugin.md index 2ab06fa8c8cfe..b71e355115982 100644 --- a/docs/shared/packages/powerpack-shared-fs-cache/powerpack-shared-fs-cache-plugin.md +++ b/docs/shared/packages/powerpack-shared-fs-cache/powerpack-shared-fs-cache-plugin.md @@ -6,7 +6,7 @@ description: The powerpack-shared-fs-cache Nx plugin enables you to use an share The `@nx/powerpack-shared-fs-cache` plugin enables you to use an shared file system directory instead of Nx Cloud to host your remote cache. You are responsible for the sharing mechanism for the directory, but the plugin ensures that Nx correctly associates task metadata with the file artifacts. {% callout type="warning" title="Potential Cache Poisoning" %} -Using a shared file system folder for the remote cache opens you up to the possibility of cache poisoning. To avoid this, use [Nx Replay](/ci/features/remote-cache) or share your cache with an AWS S3 bucket using [`@nx/powerpack-s3-cache`](/nx-api/powerpack-s3-cache). +Using a shared file system folder for the remote cache opens you up to the possibility of [cache poisoning](/troubleshooting/unknown-local-cache). To avoid this, use [Nx Replay](/ci/features/remote-cache) or share your cache with an AWS S3 bucket using [`@nx/powerpack-s3-cache`](/nx-api/powerpack-s3-cache). {% /callout %} {% callout title="This plugin requires an active Nx Powerpack license" %} @@ -30,12 +30,4 @@ The `@nx/powerpack-shared-fs-cache` plugin treats your local cache directory as ### 3. Share the Cache Directory -The `@nx/powerpack-shared-fs-cache` plugin does not actually share the cache directory across your organization. If you want that functionality, use [Nx Replay](/ci/features/remote-cache) instead. Here are a few ways you could manually share the cache directory. - -#### Restore an Nx Cache Locally from a Remote Cache provided by a CI Provider - -Many CI providers allow users to restore files and directories from their cache. You can restore this folder on subsequent CI runs or use an API to download that cache folder to local developer machines. The mechanism for doing this will differ based on your CI provider. - -#### Share an Nx Cache With a Network Drive - -It is also possible to share an Nx Cache by storing it on a mounted network drive. You are responsible for ensuring that CI machines and local developer machines have access to the network drive in a consistent way. If the network drive will be mounted on different paths, you can overwrite the default `cacheDirectory` with machine specific `NX_CACHE_DIRECTORY` environment variables. +The `@nx/powerpack-shared-fs-cache` plugin does not actually share the cache directory across your organization. If you want that functionality, use [Nx Replay](/ci/features/remote-cache) instead. Your shared file system directory might be a directory that is saved and restored by a CI provider or it could be a shared network drive. diff --git a/docs/shared/recipes/running-tasks/change-cache-location.md b/docs/shared/recipes/running-tasks/change-cache-location.md index ead1684fc8376..8c3dd56191d34 100644 --- a/docs/shared/recipes/running-tasks/change-cache-location.md +++ b/docs/shared/recipes/running-tasks/change-cache-location.md @@ -2,29 +2,8 @@ By default the cache is stored locally in `.nx/cache`. Cache results are stored for a week before they get deleted. You can customize the cache location in the `nx.json` file: -{% tabs %} -{% tab label="Nx >= 17" %} - ```json {% fileName="nx.json"%} { "cacheDirectory": "/tmp/mycache" } ``` - -{% /tab %} -{% tab label="Nx < 17" %} - -```json {% fileName="nx.json"%} -{ - "tasksRunnerOptions": { - "default": { - "options": { - "cacheDirectory": "/tmp/mycache" - } - } - } -} -``` - -{% /tab %} -{% /tabs %} diff --git a/docs/shared/reference/sitemap.md b/docs/shared/reference/sitemap.md index 8847d47e0127f..526d19e9731ad 100644 --- a/docs/shared/reference/sitemap.md +++ b/docs/shared/reference/sitemap.md @@ -24,7 +24,7 @@ - [Powerpack Features](/features/powerpack) - [Run Language-Agnostic Conformance Rules](/features/powerpack/conformance) - [Define Code Ownership at the Project Level](/features/powerpack/owners) - - [Change the Remote Cache Storage Location](/features/powerpack/custom-caching) + - [Self-Host the Remote Cache](/features/powerpack/custom-caching) - [CI Features](/features/ci-features) - [Concepts](/concepts) - [Mental Model](/concepts/mental-model) From d0b973c3031ff89fddfd1814415c20df656a949a Mon Sep 17 00:00:00 2001 From: Isaac Mann Date: Mon, 23 Sep 2024 16:59:56 -0400 Subject: [PATCH 8/9] docs(core): docs/shared/features/powerpack/custom-caching.md Co-authored-by: Juri Strumpflohner --- docs/shared/features/powerpack/custom-caching.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/shared/features/powerpack/custom-caching.md b/docs/shared/features/powerpack/custom-caching.md index 5b3db9624e4f2..0257df1acf2a1 100644 --- a/docs/shared/features/powerpack/custom-caching.md +++ b/docs/shared/features/powerpack/custom-caching.md @@ -4,7 +4,7 @@ The recommended way to enable the [remote cache](/ci/features/remote-cache) is t 1. [Nx Replay](/ci/features/remote-cache): Cache is hosted on Nx Cloud servers or on-premise with an [Nx Enterprise](/enterprise) contract 2. [@nx/powerpack-s3-cache](/nx-api/powerpack-s3-cache): Cache is on a self-hosted, fully secure AWS S3 bucket -3. [@nx/powerpack-shared-fs-cache(/nx-api/powerpack-s3-cache): Cache is self-hosted and self-secured on a shared file system location +3. [@nx/powerpack-shared-fs-cache](/nx-api/powerpack-s3-cache): Cache is self-hosted and self-secured on a shared file system location The options range from fully opting in to Nx's management of the remote cache to fully managing the configuration and security of your own remote cache. From 1bb5af18c76e076a9713750c5b611ede691bb6cb Mon Sep 17 00:00:00 2001 From: Isaac Mann Date: Tue, 24 Sep 2024 08:40:36 -0400 Subject: [PATCH 9/9] docs(core): fix link --- docs/shared/features/powerpack/custom-caching.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/shared/features/powerpack/custom-caching.md b/docs/shared/features/powerpack/custom-caching.md index 0257df1acf2a1..93abf00bcd64b 100644 --- a/docs/shared/features/powerpack/custom-caching.md +++ b/docs/shared/features/powerpack/custom-caching.md @@ -22,7 +22,7 @@ Read the individual plugin documentation for specific set up instructions. {% link-card title="AWS S3 Bucket Remote Cache" type="Nx Plugin" url="/nx-api/powerpack-s3-cache" icon="AwsIcon" /%} -{% link-card title="Shared Network Drive Remote Cache" type="Nx Plugin" url="/nx-api/powerpack-s3-cache" icon="ServerIcon" /%} +{% link-card title="Shared Network Drive Remote Cache" type="Nx Plugin" url="/nx-api/powerpack-shared-fs-cache" icon="ServerIcon" /%} {% /cards %}