diff --git a/docs/generated/manifests/cloud.json b/docs/generated/manifests/cloud.json index 7640ebc9a28cb..2c4a81f9ef7ce 100644 --- a/docs/generated/manifests/cloud.json +++ b/docs/generated/manifests/cloud.json @@ -234,8 +234,8 @@ }, "/nx-cloud/private-cloud": { "id": "private-cloud", - "name": "On Prem", - "description": "Learn about Nx Cloud On Premise, dedicated Nx Cloud application hosted on your server, in your network with total private access.", + "name": "Enterprise + On Prem", + "description": "Learn about Nx Cloud Enterprise + On-Prem.", "file": "", "itemList": [ { @@ -268,6 +268,16 @@ "path": "/nx-cloud/private-cloud/auth-github", "tags": [] }, + { + "id": "ami-setup", + "name": "On-Prem VM Setup", + "description": "", + "file": "nx-cloud/private/ami-setup", + "itemList": [], + "isExternal": false, + "path": "/nx-cloud/private-cloud/ami-setup", + "tags": [] + }, { "id": "auth-gitlab", "name": "Authenticate with GitLab", @@ -307,26 +317,6 @@ "isExternal": false, "path": "/nx-cloud/private-cloud/advanced-config", "tags": [] - }, - { - "id": "kubernetes-setup", - "name": "Kubernetes Setup", - "description": "", - "file": "nx-cloud/private/kubernetes-setup", - "itemList": [], - "isExternal": false, - "path": "/nx-cloud/private-cloud/kubernetes-setup", - "tags": [] - }, - { - "id": "standalone", - "name": "Standalone", - "description": "", - "file": "nx-cloud/private/standalone", - "itemList": [], - "isExternal": false, - "path": "/nx-cloud/private-cloud/standalone", - "tags": [] } ], "isExternal": false, @@ -363,6 +353,16 @@ "path": "/nx-cloud/private-cloud/auth-github", "tags": [] }, + "/nx-cloud/private-cloud/ami-setup": { + "id": "ami-setup", + "name": "On-Prem VM Setup", + "description": "", + "file": "nx-cloud/private/ami-setup", + "itemList": [], + "isExternal": false, + "path": "/nx-cloud/private-cloud/ami-setup", + "tags": [] + }, "/nx-cloud/private-cloud/auth-gitlab": { "id": "auth-gitlab", "name": "Authenticate with GitLab", @@ -403,26 +403,6 @@ "path": "/nx-cloud/private-cloud/advanced-config", "tags": [] }, - "/nx-cloud/private-cloud/kubernetes-setup": { - "id": "kubernetes-setup", - "name": "Kubernetes Setup", - "description": "", - "file": "nx-cloud/private/kubernetes-setup", - "itemList": [], - "isExternal": false, - "path": "/nx-cloud/private-cloud/kubernetes-setup", - "tags": [] - }, - "/nx-cloud/private-cloud/standalone": { - "id": "standalone", - "name": "Standalone", - "description": "", - "file": "nx-cloud/private/standalone", - "itemList": [], - "isExternal": false, - "path": "/nx-cloud/private-cloud/standalone", - "tags": [] - }, "/nx-cloud/reference": { "id": "reference", "name": "Reference", diff --git a/docs/generated/manifests/menus.json b/docs/generated/manifests/menus.json index ccf379a5e7492..e8d3610b0fa04 100644 --- a/docs/generated/manifests/menus.json +++ b/docs/generated/manifests/menus.json @@ -2169,6 +2169,14 @@ "children": [], "disableCollapsible": false }, + { + "name": "Find the Last Successful Commit in Azure Pipelines", + "path": "/recipes/ci/azure-last-successful-commit", + "id": "azure-last-successful-commit", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, { "name": "Setting up CircleCI", "path": "/recipes/ci/monorepo-ci-circle-ci", @@ -2244,6 +2252,14 @@ "children": [], "disableCollapsible": false }, + { + "name": "Find the Last Successful Commit in Azure Pipelines", + "path": "/recipes/ci/azure-last-successful-commit", + "id": "azure-last-successful-commit", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, { "name": "Setting up CircleCI", "path": "/recipes/ci/monorepo-ci-circle-ci", @@ -3212,14 +3228,6 @@ "children": [], "disableCollapsible": false }, - { - "name": "Find the Last Successful Commit in Azure Pipelines", - "path": "/recipes/other/azure-last-successful-commit", - "id": "azure-last-successful-commit", - "isExternal": false, - "children": [], - "disableCollapsible": false - }, { "name": "Troubleshoot Cache Misses", "path": "/recipes/other/troubleshoot-cache-misses", @@ -3423,14 +3431,6 @@ "children": [], "disableCollapsible": false }, - { - "name": "Find the Last Successful Commit in Azure Pipelines", - "path": "/recipes/other/azure-last-successful-commit", - "id": "azure-last-successful-commit", - "isExternal": false, - "children": [], - "disableCollapsible": false - }, { "name": "Troubleshoot Cache Misses", "path": "/recipes/other/troubleshoot-cache-misses", @@ -3960,7 +3960,7 @@ "disableCollapsible": false }, { - "name": "On Prem", + "name": "Enterprise + On Prem", "path": "/nx-cloud/private-cloud", "id": "private-cloud", "isExternal": false, @@ -3989,6 +3989,14 @@ "children": [], "disableCollapsible": false }, + { + "name": "On-Prem VM Setup", + "path": "/nx-cloud/private-cloud/ami-setup", + "id": "ami-setup", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, { "name": "Authenticate with GitLab", "path": "/nx-cloud/private-cloud/auth-gitlab", @@ -4020,22 +4028,6 @@ "isExternal": false, "children": [], "disableCollapsible": false - }, - { - "name": "Kubernetes Setup", - "path": "/nx-cloud/private-cloud/kubernetes-setup", - "id": "kubernetes-setup", - "isExternal": false, - "children": [], - "disableCollapsible": false - }, - { - "name": "Standalone", - "path": "/nx-cloud/private-cloud/standalone", - "id": "standalone", - "isExternal": false, - "children": [], - "disableCollapsible": false } ], "disableCollapsible": false @@ -4064,6 +4056,14 @@ "children": [], "disableCollapsible": false }, + { + "name": "On-Prem VM Setup", + "path": "/nx-cloud/private-cloud/ami-setup", + "id": "ami-setup", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, { "name": "Authenticate with GitLab", "path": "/nx-cloud/private-cloud/auth-gitlab", @@ -4096,22 +4096,6 @@ "children": [], "disableCollapsible": false }, - { - "name": "Kubernetes Setup", - "path": "/nx-cloud/private-cloud/kubernetes-setup", - "id": "kubernetes-setup", - "isExternal": false, - "children": [], - "disableCollapsible": false - }, - { - "name": "Standalone", - "path": "/nx-cloud/private-cloud/standalone", - "id": "standalone", - "isExternal": false, - "children": [], - "disableCollapsible": false - }, { "name": "Reference", "path": "/nx-cloud/reference", diff --git a/docs/generated/manifests/recipes.json b/docs/generated/manifests/recipes.json index ce83e22146783..dee91d895781c 100644 --- a/docs/generated/manifests/recipes.json +++ b/docs/generated/manifests/recipes.json @@ -197,6 +197,16 @@ "path": "/recipes/ci/monorepo-ci-azure", "tags": [] }, + { + "id": "azure-last-successful-commit", + "name": "Find the Last Successful Commit in Azure Pipelines", + "description": "", + "file": "shared/recipes/azure-last-successful-commit", + "itemList": [], + "isExternal": false, + "path": "/recipes/ci/azure-last-successful-commit", + "tags": [] + }, { "id": "monorepo-ci-circle-ci", "name": "Setting up CircleCI", @@ -292,6 +302,16 @@ "path": "/recipes/ci/monorepo-ci-azure", "tags": [] }, + "/recipes/ci/azure-last-successful-commit": { + "id": "azure-last-successful-commit", + "name": "Find the Last Successful Commit in Azure Pipelines", + "description": "", + "file": "shared/recipes/azure-last-successful-commit", + "itemList": [], + "isExternal": false, + "path": "/recipes/ci/azure-last-successful-commit", + "tags": [] + }, "/recipes/ci/monorepo-ci-circle-ci": { "id": "monorepo-ci-circle-ci", "name": "Setting up CircleCI", @@ -1498,16 +1518,6 @@ "path": "/recipes/other/misc-data-persistence", "tags": [] }, - { - "id": "azure-last-successful-commit", - "name": "Find the Last Successful Commit in Azure Pipelines", - "description": "", - "file": "shared/recipes/azure-last-successful-commit", - "itemList": [], - "isExternal": false, - "path": "/recipes/other/azure-last-successful-commit", - "tags": [] - }, { "id": "troubleshoot-cache-misses", "name": "Troubleshoot Cache Misses", @@ -1763,16 +1773,6 @@ "path": "/recipes/other/misc-data-persistence", "tags": [] }, - "/recipes/other/azure-last-successful-commit": { - "id": "azure-last-successful-commit", - "name": "Find the Last Successful Commit in Azure Pipelines", - "description": "", - "file": "shared/recipes/azure-last-successful-commit", - "itemList": [], - "isExternal": false, - "path": "/recipes/other/azure-last-successful-commit", - "tags": [] - }, "/recipes/other/troubleshoot-cache-misses": { "id": "troubleshoot-cache-misses", "name": "Troubleshoot Cache Misses", diff --git a/docs/map.json b/docs/map.json index b3b6ccb843e72..a5cf73848c8c8 100644 --- a/docs/map.json +++ b/docs/map.json @@ -958,6 +958,11 @@ "id": "monorepo-ci-azure", "file": "shared/monorepo-ci-azure" }, + { + "name": "Find the Last Successful Commit in Azure Pipelines", + "id": "azure-last-successful-commit", + "file": "shared/recipes/azure-last-successful-commit" + }, { "name": "Setting up CircleCI", "id": "monorepo-ci-circle-ci", @@ -1406,11 +1411,6 @@ "id": "misc-data-persistence", "file": "shared/guides/misc-data-persistence" }, - { - "name": "Find the Last Successful Commit in Azure Pipelines", - "id": "azure-last-successful-commit", - "file": "shared/recipes/azure-last-successful-commit" - }, { "name": "Troubleshoot Cache Misses", "id": "troubleshoot-cache-misses", @@ -1540,9 +1540,9 @@ ] }, { - "name": "On Prem", + "name": "Enterprise + On Prem", "id": "private-cloud", - "description": "Learn about Nx Cloud On Premise, dedicated Nx Cloud application hosted on your server, in your network with total private access.", + "description": "Learn about Nx Cloud Enterprise + On-Prem.", "itemList": [ { "name": "Get Started", @@ -1559,6 +1559,11 @@ "id": "auth-github", "file": "nx-cloud/private/auth-github" }, + { + "name": "On-Prem VM Setup", + "id": "ami-setup", + "file": "nx-cloud/private/ami-setup" + }, { "name": "Authenticate with GitLab", "id": "auth-gitlab", @@ -1578,16 +1583,6 @@ "name": "Advanced Configuration", "id": "advanced-config", "file": "nx-cloud/private/advanced-config" - }, - { - "name": "Kubernetes Setup", - "id": "kubernetes-setup", - "file": "nx-cloud/private/kubernetes-setup" - }, - { - "name": "Standalone", - "id": "standalone", - "file": "nx-cloud/private/standalone" } ] }, diff --git a/docs/nx-cloud/private/ami-setup.md b/docs/nx-cloud/private/ami-setup.md new file mode 100644 index 0000000000000..a52939dbfcf43 --- /dev/null +++ b/docs/nx-cloud/private/ami-setup.md @@ -0,0 +1,170 @@ +# Setting up a dedicated NxCloud VM + +## AWS EC2 + +1. Login to your AWS Console and select [the top image published here](https://console.aws.amazon.com/ec2/v2/home?home#Images:visibility=public-images;imageName=nx-cloud;owner=623002322076;sort=desc:imageName) +2. Launch a new instance from that AMI +3. Recommended instance type: `t3.2xlarge` +4. You will need to SSH into the instance once it's created: + - Use an existing SSH key-pair that you already have installed locally. + - [Or create a new one and download the keys locally](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html?icmpid=docs_ec2_console#having-ec2-create-your-key-pair) + - Then select your new SSH pair from the list +5. Networking: + - Allow the instance to receive HTTP and HTTPS traffic + - Allow SSH from your current IP +6. Leave the storage options as they are +7. "Launch instance" +8. Wait 10 minutes, then navigate to your instance's IP in the browser. You should see the NxCloud dashboard! + +![NxCloud landing page](/nx-cloud/private/images/nx-cloud-landing.png) + +### Your NxCloud URL + +1. At this point, your instance will have a public IP accessible from the browser. + - You can consider this IP the URL of NxCloud, and proceed with the below steps and all will work fine! +2. You might want, however, to add a Load Balancer in front of the instance, with an explicit domain (e.g. https://my-nxcloud.my-org.com). + - This is strongly recommended because you will be able to upgrade/restart/re-configure your NxCloud EC2 instance while keeping the NxCloud URL static. + - Create an [application load balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/create-application-load-balancer.html) + - You will need to create a certificate for your domain to assign to the LB + - And you will need to target your EC2 instance from the LB + - You should now have a permanent domain pointing to your NxCloud instance + +Once you have your NxCloud URL proceed to the below steps! + +### Configuring your NxCloud instance + +1. Create a new `myconfiguration.yaml` file with the below contents + +```yaml +# This is all you need to get the baseline of your nx-cloud instance configured! + +# Set the external URL your instance is running on. This is the URL from the previous step +nxCloudAppURL: 'https://nx-cloud.on.my-domain.ca' + +secret: + # set your initial admin password for logging into the app + adminPassword: 'correcthorsebatterystaple' +``` + +2. Apply the configuration: + +```bash +scp -r ./myconfiguration.yaml nx-cloud@:~/config/user/update.yaml +``` + +That's it! After a few minutes, you should be able to log-in with: + +- username: `admin` +- password: `` + +### Applying the license + +Once you log-in, you will see an organisation has been created for you. + +1. You can rename it or create a new organization. +2. Navigate to your new organization's page and send us it's id + - It should look something like this: https://your-url.com/orgs/649f240f7fb955000c1fd10b/workspaces +3. We will then give you a License Key which you can apply on your org's billing page + +### Connecting to your NxCloud instance + +In your Nx workspace, you can enable NxCloud by running: + +```bash +NX_CLOUD_API="https://nx-cloud.on.my-domain.ca" npx nx connect +``` + +If it doesn't work, there might be an issue with unrecognized certificates on your instance. You can try running with: + +```bash +NODE_TLS_REJECT_UNAUTHORIZED=0 NX_CLOUD_API="https://nx-cloud.on.my-domain.ca" npx nx connect +``` + +Although we have [a full guide here](https://github.com/nrwl/nx-cloud-helm/blob/main/PROXY-GUIDE.md#nxcloud-runner-proxy-issues) for dealing with self-signed certificates. + +### Advanced configuration and auth + +You can optionally enable authentication using your preferred SSO provider: + +- GitHub +- Bitbucket +- GitLab +- SAML (Okta, Azure AD etc.) + +```yaml +# This is all you need to get the baseline of your nx-cloud instance configured! + +# only use this if you'd like to use any of the newer NxCloud version from here: https://nx.dev/nx-cloud/reference/release-notes#docker-containers +# global.imageTag: '' + +# Set the external URL your instance is running on +nxCloudAppURL: 'https://nx-cloud.on.my-domain.ca' + +# Uncomment (along with github secrets below) to enable working with GitHub pull requests or github auth +#github: +# auth: +# enabled: false +# pr: +# apiUrl: '' # this is only needed if you have a self-hosted github instance + +#gitlab: +# apiUrl: '' # this is only needed if you have a self-hosted gitlab instance +# auth: +# enabled: false + +# we do not support self-hosted bitbucket instances +#bitbucket: +# auth: +# enabled: false + +#saml: +# auth: +# enabled: false + +# Provide plaintext values for your application to use. We will extract them, +# store them within the application runtime, and scrub the plaintext ones from +# the filesystem +secret: + # set your initial admin password for logging into the app + # see here: https://nx.dev/nx-cloud/private-cloud/auth-single-admin + adminPassword: 'correcthorsebatterystaple' + + # If you want to enable GitHub Login, just provide your client id & secret, we handle the rest + # see here: https://nx.dev/nx-cloud/private-cloud/auth-github + githubAuthClientId: 'my_client_id' + githubAuthClientSecret: 'my_client_secret' + + # The same goes for GitLab authentication + # see here: https://nx.dev/nx-cloud/private-cloud/auth-gitlab + # gitlabAppId: 'my_gitlab_app_id' + # gitlabAppSecret: 'my_gitlab_app_secret' + + # Bitbucket too! If these are uncommented, BB auth is automatically enabled + # see here: https://nx.dev/nx-cloud/private-cloud/auth-bitbucket + # bitbucketAppId: 'bitbucket_app_id' + # bitbucketAppSecret: 'bitbucket_app_secret' + + # SAML auth + # see here: https://nx.dev/nx-cloud/private-cloud/auth-saml + # samlEntryPoint: 'your_saml_entry_point' + # samlCert: 'saml_cert' +``` + +### Upgrades + +We send out emails with every new NxCloud release to all our Enterprise customers: + +1. You can view your current version at the `/version` route: https://your-nx-cloud-url.com/version +2. [And these are the latest NxCloud releases](https://nx.dev/nx-cloud/reference/release-notes#docker-containers) + +To upgrade to a newer version, add the below line to your `myconfiguration.yml` file: + +```yaml +global.imageTag: '2306.01.2' # set the version of nx-cloud you'd like +``` + +And apply the changes: + +```bash +scp -r ./myconfiguration.yaml nx-cloud@:~/config/user/update.yaml +``` diff --git a/docs/nx-cloud/private/get-started.md b/docs/nx-cloud/private/get-started.md index 5348dfb5be42c..f24f788548710 100644 --- a/docs/nx-cloud/private/get-started.md +++ b/docs/nx-cloud/private/get-started.md @@ -1,23 +1,62 @@ -# Running Nx Cloud on Prem +# Running Nx Cloud Enterprise -Nx Cloud can be deployed to your cloud, which gives you full control of your data, with no external API calls. +We offer multiple ways of running NxCloud for our Enterprise customers. The below options are listed in recommended order, from easiest to most complex in +terms of set-up and maintenance for your team. Please carefully consider your organization's requirements and level of infrastructure expertise before deciding on +a deployment option. -This solution is included as part of the Nx Enterprise package. You can learn more about it at [nx.app/enterprise](https://nx.app/enterprise). +Also, please make sure to [get in touch with us first](https://nx.app/enterprise?utm_source=nx.dev) so we can start creating an Enterprise package +that best fits your needs, and discuss any questions you might have! -Nx Cloud can be deployed in two ways: +## Clusters managed by us -- Using Kubernetes (several containers working together) -- Using a single standalone container (NOT RECOMMENDED) +### Multi-tenant -The flags and the capabilities are the same between the two, but the Kubernetes setup is more robust and better -documented. +The quickest way and easiest way to get up and running with NxCloud is using one of our existing secure, multi-tenant managed clusters: + +- https://nx.app/ +- Or, if you'd like all of your data to be hosted in Europe, you can use https://eu.nx.app/ + +You get the same level of security, dedicated support, SSO/SAML auth options and predictable seat-based pricing as all our other hosting options, but you won't have +to manage the instance yourself. + +We also offer an uptime SLA guarantee of 99.98% for our Enterprise customers, SOC certificates on request, and we're happy to meet with your security teams if they +have questions, or fill in security questionnaires. We also maintain a [Status Page here](https://status.nx.app/). + +To start with this option, it's as easy as running `npx nx connect` in your Nx workspace! + +### Single-tenant instance + +If you have very specific requirements, then we can also offer to host NxCloud for you in an isolated/single-tenant cluster. + +We'll be able to discuss specific requirements such as: + +- Specific regions you want your data to be in +- Network isolation / dedicated VPCs +- Dedicated instances +- Storage encryption +- Storage replication / redundancy + +This would be a "best of both worlds" option, as it would free you up from managing the instance yourself, but you will get to define specific parameters of how it should it run. +Your data and the NxCloud will run in complete isolation and will only serve your company. There will be no external API calls to any services outside of the cluster we set-up for you. + +Once you let us know you'd like this option, depending on the agreed requirements, it might take a few days to get it set up. + +## On-prem, managed by your organization + +#### Self-contained VM + +If you would like to host NxCloud yourself, within your organization's infrastructure, the easiest way to set it up is as a self-contained VM. + +Refer to our ["Self-contained VM" guide](/nx-cloud/private-cloud/ami-setup) for instructions on running NxCloud on Amazon EC2. + +#### Multi-node setup with Kubernetes + +The options above remove most of the maintenance burden required on your part, so we strongly recommend them! They also don't require too much infrastructure expertise. + +We do offer, however, a multi-node Kubernetes setup, that is deployed via Helm. You can head over to our [Helm repository](https://github.com/nrwl/nx-cloud-helm/) to explore this option. ## Resources -- [Kubernetes Setup Instructions](/nx-cloud/private-cloud/kubernetes-setup) -- [Nx Cloud K8s Example + All Config Options](https://github.com/nrwl/nx-cloud-helm) -- [Nx Cloud K8s Example + All Config Options (no Helm)](https://github.com/nrwl/nx-cloud-helm/tree/main/no-helm) -- [Standalone Container](/nx-cloud/private-cloud/standalone) - [GitHub PR Integration](/nx-cloud/set-up/github) - [Auth (Basic)](/nx-cloud/private-cloud/auth-single-admin) - [GitHub Auth](/nx-cloud/private-cloud/auth-github) diff --git a/docs/nx-cloud/private/images/nx-cloud-landing.png b/docs/nx-cloud/private/images/nx-cloud-landing.png new file mode 100644 index 0000000000000..f5d3d9dcc0e43 Binary files /dev/null and b/docs/nx-cloud/private/images/nx-cloud-landing.png differ diff --git a/docs/nx-cloud/private/kubernetes-setup.md b/docs/nx-cloud/private/kubernetes-setup.md deleted file mode 100644 index 330e694d79fe7..0000000000000 --- a/docs/nx-cloud/private/kubernetes-setup.md +++ /dev/null @@ -1,282 +0,0 @@ -# Set Up Nx Cloud on Kubernetes - -A lot of organizations deploy Nx Cloud to Kubernetes. - -This guide references the [nx-cloud-helm](https://github.com/nrwl/nx-cloud-helm) repo which contains: - -- Nx Cloud Helm Chart -- Instructions on how to install Nx Cloud using Helm -- Instructions on how to install Nx Cloud using kubectl. See [here](https://github.com/nrwl/nx-cloud-helm/blob/main/no-helm/README.md). - -## Deployments on AWS/EKS - -If you're deploying on EKS, check out our [AWS Guide](https://github.com/nrwl/nx-cloud-helm/blob/main/aws-guide/AWS-GUIDE.md). Otherwise, continue reading below. - -## Installing Using Helm - -Steps: - -1. Deploy MongoDB Kubernetes Operator - - using helm: https://github.com/mongodb/helm-charts - - using kubectl: https://github.com/mongodb/mongodb-kubernetes-operator -2. Create a mongodb replica set -3. Create a secret -4. Install Nx Cloud using helm - -### Step 1: Deploy MongoDB Kubernetes Operator - -If you are using a hosted MongoDB installation (e.g., Mongo Atlas or CosmosSB, or you are running one yourself), you can -skip steps 1 and 2. - -``` -> helm repo add mongodb https://mongodb.github.io/helm-charts -> helm install community-operator mongodb/community-operator -``` - -### Step 2: Deploy a MongoDB replica set - -``` -> kubectl apply -f examples/mongodb.yml -``` - -This will create a secret. You can get the value of the secret as follows: - -> kubectl get secret cloud-mongodb-nrwl-api-admin-user -o go-template='{{range $k,$v := .data}}{{"### "}}{{$k}}{{"n"}}{{$v|base64decode}}{{"nn"}}{{end}}' - -You might need to wait a bit for the Pods to be created before this secret will be available. - -The output of the command can be a bit confusing (you are only interested in the second part of the output). The default connection string for the Mongo Community Operator will look like -this: `mongodb+srv://admin-user:DB_PASSWORD@cloud-mongodb-svc.default.svc.cluster.local/nrwl-api?replicaSet=cloud-mongodb&ssl=false` -. You should be able to use this value. - -Take this connection string and paste it into your `examples/secret.yml`, replacing the placeholder value. - -### Step 3: Create a secret - -With the values updated, create a secret by running `kubectl apply -f examples/secret.yml` - -### Step 4: Install Nx Cloud using helm - -``` -> helm repo add nx-cloud https://nrwl.github.io/nx-cloud-helm -> helm install nx-cloud nx-cloud/nx-cloud --values=overrides.yml -``` - -`examples/overrides` contains the min overrides files. You need to provision: - -1. The image tag you want to install -2. `nxCloudAppURL` which is the url used to access ingress from CI and dev machines ( - e.g., `https://nx-cloud.myorg.com`). -3. `secret/name` the name of the secret you created in Step 3. -4. `secret/nxCloudMongoServerEndpoint`, the name of the key from the secret. - 5`secret/adminPassword`, the name of the key from the secret. - -If you only applied the secret from Step 3, the only thing you will need to change is `nxCloudAppURL`. - -## Cloud Containers - -The installation will create the following: - -1. nx-cloud-frontend (deployment) -2. nx-cloud-api (deployment) -3. nx-cloud-nx-api (deployment) -4. nx-cloud-file-server (deployment) -5. nx-cloud-aggregator (cron job) - -## Ingress, IP, Certificates - -You can configure Ingress. For instance, the following will see the ingress class to 'gce', the global static ip name -to 'nx-cloud-ip', and will set a global Google managed certificate. - -```yaml -image: - tag: 'latest' - -nxCloudAppURL: 'https://nx-cloud.myorg.com' - -ingress: - class: 'gce' - globalStaticIpName: 'nx-cloud-ip' - managedCertificates: 'cloud-cert' - -secret: - name: 'cloud' - nxCloudMongoServerEndpoint: 'NX_CLOUD_MONGO_SERVER_ENDPOINT' - adminPassword: 'ADMIN_PASSWORD' -``` - -This configuration will look different for you. You will have a different global static ip and your cert name will also -be different. If you are interested in creating the two using GKE, check out the following links: - -- [Reserving a static external IP address](https://cloud.google.com/compute/docs/ip-addresses/reserve-static-external-ip-address) -- [Using Google-managed SSL certificates](https://cloud.google.com/kubernetes-engine/docs/how-to/managed-certs) - -If you aren't using GKE, `ingress.class` will also be different. For example, see [our example config for AWS](https://github.com/nrwl/nx-cloud-helm/blob/main/aws-guide/helm-values.yml#L7) or check out the AWS Load Balancer set-up section [here for AWS set-up instructions.](https://github.com/nrwl/nx-cloud-helm/blob/main/aws-guide/AWS-GUIDE.md#3-install-a-load-balancer) - -If you need to have a detailed Ingress configuration, you can tell the package to skip defining ingress: - -```yaml -image: - tag: 'latest' - -nxCloudAppURL: 'https://nx-cloud.myorg.com' - -ingress: - skip: true -``` - -⤵️ and then define it yourself - -```yaml -apiVersion: networking.k8s.io/v1 -kind: Ingress -metadata: - name: nx-cloud-ingress - annotations: - - labels: - app: nx-cloud -spec: - rules: - - http: - paths: - # define the next /file section only if you use the built-in file server - - path: /file - pathType: Prefix - backend: - service: - name: nx-cloud-file-server-service - port: - number: 5000 - - path: /nx-cloud - pathType: Prefix - backend: - service: - name: nx-cloud-nx-api-service - port: - number: 4203 - - path: /api - pathType: Prefix - backend: - service: - name: nx-cloud-nrwl-api-service - port: - number: 4000 - - path: /graphql - pathType: Prefix - backend: - service: - name: nx-cloud-nrwl-api-service - port: - number: 4000 - - path: /auth - pathType: Prefix - backend: - service: - name: nx-cloud-nrwl-api-service - port: - number: 4000 - - path: /download - pathType: Prefix - backend: - service: - name: nx-cloud-nrwl-api-service - port: - number: 4000 - - path: /download - - pathType: Prefix - backend: - service: - name: nx-cloud-frontend-service - port: - number: 8080 -``` - -### Step 5: Connect Your Workspace - -Run `NX_CLOUD_API=https://nx-cloud.myorg.com nx connect`. Click on the link to connect the workspace -to your admin account. - -## Variations - -### External File Storage - -If you use AWS or Azure, you can configure Nx Cloud to store cached artifacts on S3 or Azure Blob. In this case, you -won't need the PVC or the file-server container. S3 and Azure Blob also tend to be faster. - -For S3 buckets, see the [AWS Guide](https://github.com/nrwl/nx-cloud-helm/blob/main/aws-guide/AWS-GUIDE.md#6-external-s3-access) - -For Azure: - -```yaml -image: - tag: 'latest' - -nxCloudAppURL: 'https://nx-cloud.myorg.com' - -azure: - enabled: true - container: 'nx-cloud' - -secret: - name: 'cloudsecret' - nxCloudMongoServerEndpoint: 'NX_CLOUD_MONGO_SERVER_ENDPOINT' - adminPassword: 'ADMIN_PASSWORD' - azureConnectionString: 'AZURE_CONNECTION_STRING' -``` - -Note that the secret for setting up Azure must contain `AZURE_CONNECTION_STRING`. - -### GitHub Auth - -To use GitHub for user authentication, you can use the following configuration: - -```yaml -image: - tag: 'latest' - -nxCloudAppURL: 'https://nx-cloud.myorg.com' - -github: - auth: - enabled: true - -secret: - name: 'cloudsecret' - nxCloudMongoServerEndpoint: 'NX_CLOUD_MONGO_SERVER_ENDPOINT' - githubAuthClientId: 'GITHUB_AUTH_CLIENT_ID' - githubAuthClientSecret: 'GITHUB_AUTH_CLIENT_SECRET' -``` - -Note that the secret must contain `GITHUB_AUTH_CLIENT_ID` and `GITHUB_AUTH_CLIENT_SECRET`. -Read [here](https://nx.dev/nx-cloud/private-cloud/auth-github) on how to get those values. - -### GitHub Integration - -To enable the GitHub PR integration, you can use the following configuration: - -```yaml -image: - tag: 'latest' - -nxCloudAppURL: 'https://nx-cloud.myorg.com' - -github: - pr: - enabled: true - # apiUrl: '' uncomment when using github enterprise - -secret: - name: 'cloudsecret' - nxCloudMongoServerEndpoint: 'NX_CLOUD_MONGO_SERVER_ENDPOINT' - githubWebhookSecret: 'GITHUB_WEBHOOK_SECRET' - githubAuthToken: 'GITHUB_AUTH_TOKEN' -``` - -Note that the secret must contain `GITHUB_WEBHOOK_SECRET` and `GITHUB_AUTH_TOKEN`. -Read [here](https://nx.dev/nx-cloud/private-cloud/github) on how to get those values. - -## More Information - -You can find more information about Nx Cloud and running it on -prem [here](https://nx.dev/nx-cloud/private-cloud/get-started). diff --git a/docs/nx-cloud/private/standalone.md b/docs/nx-cloud/private/standalone.md deleted file mode 100644 index 7f1b34491aa87..0000000000000 --- a/docs/nx-cloud/private/standalone.md +++ /dev/null @@ -1,315 +0,0 @@ -# Running a Standalone Container - -Nx Cloud can be deployed in two ways: - -- [Using Kubernetes](https://github.com/nrwl/nx-cloud-helm) (several containers working together) -- Using a single standalone container (NOT RECOMMENDED) - -The flags and the capabilities are the same between the two, but the Kubernetes setup is more robust and better -documented. This document covers the latter version. - -**Nx Cloud consists of 3 parts:** - -1. The stateless Nx Cloud service -2. MongoDB database -3. File server - -By default, the container created by the `nxprivatecloud/single-image` image will create two of them: the stateless Nx Cloud service, and the file server. Using a single container is the easiest way to set it up, but it isn't the most robust way to run Nx Cloud. - -You will then need to host the database separately: - -- Either by using a service such as Mongo Atlas -- Or running it yourself. For that, we created the `nxprivatecloud/nx-cloud-mongo` image. - -The instructions will go through running the embedded file server, and then, at the end, will talk about hosting your cached artefacts on an external service, such as Amazon S3. - -## Running Nx Cloud - -### Step 1: Pull the Image - -```shell -> docker pull nxprivatecloud/single-image -``` - -To update the version of Nx Cloud, pull the new version of the image and run it against the same mount (see -below). - -### Step 2: Create a Container - -Depending on how your infrastructure is set up, you can either run Nx Cloud using HTTPS or HTTP. If you have a -proxy/load-balancer in front of Nx Cloud, you will likely want to run Nx Cloud using HTTP (the -proxy/load-balancer will handle TLS). Otherwise, you will likely want to run Nx Cloud using HTTPS. - -**To create a container:** - -1. You will need to create a directory on the host machine where data will be stored. (_This is not necessary if you are - running the file server separately. See below._) -2. You will need to know the URL that the Nx Cloud installation can be accessed by (see `NX_CLOUD_APP_URL` below). - - `NX_CLOUD_APP_URL` should be accessible from your CI and dev machines. - - `NX_CLOUD_APP_URL` can be set with an HTTP or HTTPS url. In a case where you are using a proxy/load-balancer, you - can still put HTTPS (the url will be resolved by the proxy before hitting the app). - - `NX_CLOUD_APP_URL` is likely to be an external IP/domain of the load balancer. -3. If you are running Nx Cloud using HTTPS, you need to generate or obtain an SSL certificate and an SSL private - key. - -**Once you obtain all the needed information, you can run the following:** - -**Using HTTPS** - -```shell -> docker create --name cloud \ - - -p 443:8081 \ - -e CERT_KEY="$(cat ./tools/certs/key.pem)" \ - -e CERT="$(cat ./tools/certs/cert.pem)" \ - -e NX_CLOUD_APP_URL="https://cloud.myorg.com" \ - -e ADMIN_PASSWORD=admin \ - -v /data/private-cloud:/data nxprivatecloud/nxcloud:latest -``` - -**Using HTTP (no proxy)** - -```shell -> docker create --name cloud \ - - -p 80:8081 \ - -e NX_CLOUD_APP_URL="http://cloud.myorg.com" \ - -e ADMIN_PASSWORD=admin \ - -v /data/private-cloud:/data nxprivatecloud/nxcloud:latest -``` - -**Using HTTPS via proxy** - -```shell -> docker create --name cloud \ - -p 80:8081 \ - -e NX_CLOUD_APP_URL="https://cloud.myorg.com" \ - -e ADMIN_PASSWORD=admin \ - -v /data/private-cloud:/data nxprivatecloud/nxcloud:latest -``` - -**Let's see what those options mean:** - -- `443:8081` maps the internal port 8081 to 443, so it can be accessed in the browser without specifying the port. 80: - 8081 works the same way when you use HTTP instead of HTTPS. -- `CERT_KEY` and `CERT` contain the values of private key and cert. The file extensions of the cert and key files can be - different, but as long as they are in the PEM format (which is the case if you use, for instance, OpenSSL), the - command will work. -- `NX_CLOUD_APP_URL` is the URL the cloud can be accessed by (e.g., `https://nxcloud.privateurl.com`). **Important: - Unless you are experimenting, it won't be localhost. It has to be the URL that your CI and your developer machine can - reach. Also note, there is no trailing slash in the URL.** -- `ADMIN_PASSWORD` contains the password of the admin user. The admin user is created the first time you run cloud, you - can remove this env variable after that. Instead of an admin password, you can also - follow [the instructions here](/nx-cloud/private-cloud/auth-github) to set up GitHub auth. -- `-v /data/private-cloud:/data` sets up the volume where the data (the cached artefacts) is stored. `/data/private-cloud` refers to a folder - on your machine, `/data` is the shareable folder from the Docker image. - -### Step 3: Run the Container - -Once you create the container, you can start it using: - -```shell -> docker start cloud -``` - -Imagine `NX_CLOUD_APP_URL` is set to `https://nxcloud.privateurl.com`. - -Now, go to https://nxcloud.privateurl.com to see cloud running. You can log into the account -using `admin/ADMIN_PASSWORD`. - -### Step 4: Connect Your Workspace - -Run `NX_CLOUD_API=https://nxcloud.privateurl.com` nx connect. Click on the link to connect the workspace -to your admin account. - -### Optional step 5: set up GitHub auth - -Follow the [instructions here](/nx-cloud/private-cloud/auth-github) to set up GitHub OAuth authentication so you can -invite other members in your team to the workspace. - -### Optional step 6: set up GitHub Pull Request integration - -You can [optionally configure Nx Cloud](/nx-cloud/set-up/github) to post build stats directly on your GitHub -pull requests. - -### Optional step 7: Setting Up Proxy - -If your container cannot access `api.nrwl.io` directly and has to talk via a proxy, you can -add `-e HTTPS_PROXY="https://myproxy.myorg.com"` to the container creation command. - -## Running the Mongo Database - -Nx Cloud uses MongoDB to store its metadata. You will need to provision the `NX_CLOUD_MONGO_SERVER_ENDPOINT` env variable when -creating a container, like so: - -```shell --e NX_CLOUD_MONGO_SERVER_ENDPOINT="mongodb://domain-with-mongo:27017/nrwl-api" -``` - -By default, Nx Cloud requires Mongo 4.2+. If you are using an older version of Mongo (for instance, if you are using -Cosmos DB), please add - -```shell --e NX_CLOUD_USE_MONGO42=false -``` - -### Deploy Mongo on your Kubernetes engine or Docker VM - -See [here](https://github.com/nrwl/nx-cloud-helm/blob/main/MONGO-OPERATOR-GUIDE.md) for a full guide on running Mongo yourself. - -### Using CosmosDB - -If you are deploying to Azure, you might have access to CosmosDB. See here for more information. - -### Using Mongo Atlas - -[Mongo Atlas](https://mongodb.com/) is a great option for deploying MongoDB. - -## Using External File Storage - -By default, Nx Cloud is going to start a file server and store the cached artifacts in the provided volume. But -you can also configure Nx Cloud to use an external file storage. At the moment, only S3 and Azure Blob are -supported. - -### Using S3/Minio - -To configure S3 as a file storage, provision the `AWS_S3_ACCESS_KEY_ID`, `AWS_S3_SECRET_ACCESS_KEY`, and `AWS_S3_BUCKET` -env variables when creating the Nx Cloud docker container, like so: - -```shell --e AWS_S3_ACCESS_KEY_ID="SOMEKEY" --e AWS_S3_SECRET_ACCESS_KEY="SOMESECRETKEY" --e AWS_S3_BUCKET="nx-cache-bucket-name" -``` - -If you are using an accelerated bucket, add: `-e AWS_S3_ACCELERATED=true` - -If you are using a local S3 installation (e.g., Minio), you can set the endpoint as follows: - -```shell --e AWS_S3_ENDPOINT="https://local-installation.myorg.com" --e AWS_S3_ACCESS_KEY_ID="SOMEKEY" --e AWS_S3_SECRET_ACCESS_KEY="SOMESECRETKEY" --e AWS_S3_BUCKET="nx-cache-bucket-name" -``` - -{% callout type="note" title="On cache item expiration time" %} -Remember to -set [a cache item expiration time](https://docs.aws.amazon.com/AmazonS3/latest/userguide/lifecycle-expire-general-considerations.html) -. The default is currently 4 weeks. If you would like to keep items for longer, for example for 8 weeks, please remember -to set the `NX_CACHE_EXPIRATION_PERIOD_IN_DAYS=56` env variable as well, so the container knows when to expire the Mongo -cache entries as well. -{% /callout %} - -### Using Azure - -To configure Azure Blob as a file storage, provision the `AZURE_CONNECTION_STRING`, `AZURE_CONTAINER` env variables when -creating the Nx Cloud docker container, like so: - -```shell --e AZURE_CONNECTION_STRING="SOME-CONNECTION-STRING" --e AZURE_CONTAINER="files" -``` - -To obtain the `AZURE_CONNECTION_STRING` value go to your "Storage Account" and click on "Access Keys". You will also -need to create a container in your storage account before starting the Nx Cloud container. - -If you use an external file storage solution, you don't have to provision the volume. - -{% callout type="note" title="Cache expiration time" %} -See note above about setting a cache expiration time. For Azure blob -storage, [see this guide](https://docs.microsoft.com/en-us/azure/cdn/cdn-manage-expiration-of-blob-content). -{% /callout %} - -## Configure Memory Limits - -By default, the Nx Cloud container is configured to run on an instance with 8GB of RAM. - -If you have a container with 4GB of RAM, you can decrease the memory limits by setting the following env variables: - -- `NX_CLOUD_FILE_SERVER_MEMORY_LIMIT=500` -- `NX_CLOUD_API_MEMORY_LIMIT=800` - -Example: - -```shell -> docker create --name cloud \ - -p 80:8081 \ - -e NX_CLOUD_APP_URL="https://cloud.myorg.com" \ - -e ADMIN_PASSWORD=admin \ - -e NX_CLOUD_FILE_SERVER_MEMORY_LIMIT=500 \ - -e NX_CLOUD_API_MEMORY_LIMIT=800 \ - -v /data/private-cloud:/data nxprivatecloud/nxcloud:latest -``` - -The right amount of RAM depends heavily on how you run Nx Cloud. - -- The `NX_CLOUD_FILE_SERVER_MEMORY_LIMIT` value is only relevant if you use the built-in file server. - -For instance, if you use S3 to store the cached artifacts, even 2GB might be sufficient. You can set the following limit: - -- `NX_CLOUD_API_MEMORY_LIMIT=800` - -If you run everything in the Nx Cloud container, then 5GB is much preferred. - -## Configure Artifact Expiration When Using Built-in File Server - -By default, the Nx Cloud container is going to remove cached artifacts after two weeks. You can change it by setting `NX_CACHE_EXPIRATION_PERIOD_IN_DAYS` when starting the container. - -Example: - -```shell -> docker create --name cloud \ - -p 80:8081 \ - -e NX_CLOUD_APP_URL="https://cloud.myorg.com" \ - -e ADMIN_PASSWORD=admin \ - -e NX_CACHE_EXPIRATION_PERIOD_IN_DAYS=5 \ - -v /data/private-cloud:/data nxprivatecloud/nxcloud:latest -``` - -## Self-Signed Certificates - -If you have a self-signed certificate, you will have to provision `NODE_EXTRA_CA_CERTS`. The env variable should point to a PEM file with either your certificate, or the root certificate your certificate was created from. Though this can be accomplished with a CLI command like `NODE_EXTRA_CA_CERTS=./tools/certs/cert.crt nx test myapp`, you will most likely want to configure it as a global env variable (for instance in your `.bashrc` file). - -A self-sign certificate registered in your OS won't be picked up by Node. Node requires you to provision `NODE_EXTRA_CA_CERTS`. - -## Migration guide from `nxprivatecloud/nxcloud` to `nxprivatecloud/single-image` - -The old version of our Docker image, `nxprivatecloud/nxcloud`, is no longer being maintained. This section will explain how to migrate to the new standalone image, `nxprivatecloud/single-image`. - -Unlike `nxprivatecloud/nx-cloud`, the `nxprivatecloud/single-image` container does not come with MongoDB included. This makes for a much simpler image, based on Alpine (and not Ubuntu), with less chances for security vulnerabilities. However, it does require you to connect to an external Mongo instance. Below we'll cover the two possible migration scenarios. - -#### You are connecting to an external Mongo instance - -If you are currently connecting to an external Mongo instance, then migrating to the new image is as simple as switching the Docker tag from `nxprivatecloud/nxcloud` to `nxprivatecloud/single-image`. All the other configuration options can stay the same. - -#### You are running Mongo inside the Docker image - -If you are currently relying on the image to host Mongo, we will need to move that to an external instance. - -##### Starting fresh with a dedicated Mongo instance - -1. We recommend setting up a dedicated Mongo host, on Atlas [as described above](#using-mongo-atlas). This means you will lose you current workspace set-up, but it is the easiest migration path and the most maintanable one. - 1. To do this, get the connection string from Mongo Atlas - 2. And configure the image with it: `-e NX_CLOUD_MONGO_SERVER_ENDPOINT="mongodb://domain-with-mongo:27017/nrwl-api"` - 3. That's it! -2. If you cannot use Atlas or Azure CosmosDB within your org, then you'll need to run our dedidcated Mongo Docker image. Instructions for this approach are described below. - -##### Migrating your data to a separate self-hosted Mongo instance - -1. When running the image, you are probably mapping to the host volume like this `-v /data/private-cloud:/data:Z` -2. That data folder is where the image stores all its persistent data that needs exist between restarts or updates of the image. Inside it you'll find: - - 1. In the old image (`nxprivatecloud/nx-cloud`): - 1. `/data/file-server`: if you are using the built-in file-server, this is where you'll find all the cached artefacts. If you are using an external S3 buckets this folder won't exist. - 2. `/data/mongo`: this is where Mongo stores all its files. - 2. In the new image (`nxprivatecloud/single-image`): - 1. `/data/file-server` (if using the built-in file-server, otherwise you don't need to map anything) - -3. Copy the contents of `/data/mongo` folder from the host where you previously used to run Mongo, to the new host where you'll run the dedicated Mongo image -4. Run Mongo as described [here](https://github.com/nrwl/nx-cloud-helm/blob/main/MONGO-OPERATOR-GUIDE.md) - 1. In there, you'll find instructions to map the `$PWD/mongo-data:/data/db` folder to your host - 2. Copy the data from Step 1. above into the new mapped folder above. -5. Get the connection string for the above image -6. Start your `nxprivatecloud/single-image` container with the `-e NX_CLOUD_MONGO_SERVER_ENDPOINT="mongodb://52.201.253.213:27017/?authSource=admin&directConnection=true"` env var -7. You can remove the `/data/mongo` folder from the `single-image` mapping (you will need to keep `/data/file-server` if you not using an external S3 bucket) diff --git a/docs/shared/concepts/how-caching-works.md b/docs/shared/concepts/how-caching-works.md index 3946f19574b81..ca04ec79962f6 100644 --- a/docs/shared/concepts/how-caching-works.md +++ b/docs/shared/concepts/how-caching-works.md @@ -3,7 +3,7 @@ Before running any task, Nx computes its computation hash. As long as the computation hash is the same, the output of running the task is the same. -By default, the computation hash for - say - `nx test remixapp` includes: +By default, the computation hash for something like `nx test remixapp` includes: - All the source files of `remixapp` and its dependencies - Relevant global configuration diff --git a/docs/shared/core-features/automate-updating-dependencies.md b/docs/shared/core-features/automate-updating-dependencies.md index 07a5f3f5eb21f..b2b47e7d0483a 100644 --- a/docs/shared/core-features/automate-updating-dependencies.md +++ b/docs/shared/core-features/automate-updating-dependencies.md @@ -1,16 +1,24 @@ # Automate Updating Dependencies -The Nx CLI provides the `migrate` command to help you stay up to date with the latest version of Nx. +Keeping a codebase updated with the latest changes in your framework of choice and tooling can be challenging. Not to mention that "tooling maintenance work" is usually hard to squeeze into your feature sprint. -Not only does `nx migrate` update you to the latest version of Nx, but it also updates the versions of dependencies that we support and test such as Jest and Cypress. You can also use the `migrate` command to update any Nx plugin. +The `nx migrate` helps by automating the process of updating: -## Update to the latest Nx version +- package versions in your `package.json` +- configuration files (e.g. your Jest, ESLint or Nx config) +- your source code (e.g. fixing breaking changes or migrating to new best practices) + +## How does it work? + +Nx knows where its configuration files are and can therefore make sure they match the expected format or can alternatively adjust them. This automated update process, commonly referred to as "migration," becomes even more powerful when you leverage [Nx plugins](/packages). Nx plugins, which are NPM packages with a range of capabilities (code generation, task automation...), offer targeted updates based on their specific areas of responsibility. + +For example, the [Nx ESLint plugin](/packages/linter) excels at configuring linting in your workspace. With its understanding of the configuration file locations, this plugin can provide precise migration scripts to update ESLint packages in your `package.json` and corresponding configuration files in your workspace when a new version is released. Updating happens in three steps: - The installed dependencies are updated including the `package.json` (and `node_modules`). -- The source code in the repo is updated to match the new versions of packages in `package.json`. -- Remove the `migrations.json` file +- The source code in the repo is updated to match the new versions of packages according to set of instructions specified in `migrations.json` file. +- Optionally remove the `migrations.json` file or keep it to re-run it in different Git branches ### Step 1: Updating dependencies and generating migrations @@ -20,11 +28,7 @@ First, run the `migrate` command: nx migrate latest # same as nx migrate nx@latest ``` -You can also specify the name of the package and the version: - -```shell -nx migrate nx@version # you can also specify version -``` +Note you can also specify an exact version by replacing `latest` with `nx@`. This fetches the specified version of the `nx` package, analyzes the dependencies and fetches all the dependent packages. The process keeps going until all the dependencies are resolved. This results in: @@ -41,11 +45,7 @@ At this stage, after inspecting the `package.json`, you may wish to manually run ### Step 2: Running migrations -The next step in the process involves using the `migrate` CLI in order to apply the migrations that were generated in `migrations.json` in the previous step. - -Each Nx plugin is able to provide a set of migrations which are relevant to particular versions of the package, and so `migrations.json` will only contain migrations which are appropriate for the update you are currently applying. - -The common case is that you will simply apply all migrations from the generated JSON file, exactly as they were generated in the previous step, by running: +You can now run the actual code migrations that were generated in the `migrations.json` in the previous step. ```shell nx migrate --run-migrations @@ -53,12 +53,14 @@ nx migrate --run-migrations This will update your source code in your workspace in accordance with the implementation of the various migrations which ran and all the changes will be unstaged ready for you to review and commit yourself. +Note that each Nx plugin is able to provide a set of migrations which are relevant to particular versions of the package. Hence `migrations.json` will only contain migrations which are appropriate for the update you are currently applying. + ### Step 3: Cleaning up After you run all the migrations, you can remove `migrations.json` and commit any outstanding changes. Note: You may want to keep the `migrations.json` until every branch that was created before the migration has been merged. Leaving the `migrations.json` in place allows devs to run `nx migrate --run-migrations` to apply the same migration process to their newly merged code as well. -## Problems? +## Need to opt-out of some migrations? -If you can't run `nx migrate --run-migrations` all in one step, try the tips in [Advanced Update Process](/recipes/other/advanced-update) +Sometimes you need to temporarily opt-out from some migrations because your workspace is not ready yet. You can manually adjust the `migrations.json` or run the update with the `--interactive` flag to choose which migrations you accept. Find more details in our [Advanced Update Process](/recipes/other/advanced-update) guide. diff --git a/docs/shared/getting-started/why-nx.md b/docs/shared/getting-started/why-nx.md index 4548a78c64ccf..86a7352168b0e 100644 --- a/docs/shared/getting-started/why-nx.md +++ b/docs/shared/getting-started/why-nx.md @@ -2,7 +2,7 @@ We created Nx because developers struggle to configure, maintain and especially integrate various tools and frameworks. Setting up a system that works well for a handful of developers and at the same time, easily scales up to an entire organization is hard. This includes setting up low-level build tooling, configuring fast CI, and keeping your codebase healthy, up-to-date, and maintainable. -We wanted to provide a solution that is easy to adopt and scales. +We wanted to provide a solution that is easy to adopt and scale. ## How Does Nx Help You? diff --git a/docs/shared/monorepo-ci-azure.md b/docs/shared/monorepo-ci-azure.md index dd2292f19d82c..b2835eb561a02 100644 --- a/docs/shared/monorepo-ci-azure.md +++ b/docs/shared/monorepo-ci-azure.md @@ -8,7 +8,7 @@ Nx needs additional Git history available for `affected` to function correctly. {% /callout %} -Unlike `GitHub Actions` and `CircleCI`, you don't have the metadata to help you track the last successful run on `main`. In the example below, the base is set to `HEAD~1` (for push) or branching point (for pull requests), but a more robust solution would be to tag an SHA in the main job once it succeeds and then use this tag as a base. You can also try [using the devops CLI within the pipeline yaml](/recipes/other/azure-last-successful-commit). See the [nx-tag-successful-ci-run](https://github.com/nrwl/nx-tag-successful-ci-run) and [nx-set-shas](https://github.com/nrwl/nx-set-shas) (version 1 implements tagging mechanism) repositories for more information. +Unlike `GitHub Actions` and `CircleCI`, you don't have the metadata to help you track the last successful run on `main`. In the example below, the base is set to `HEAD~1` (for push) or branching point (for pull requests), but a more robust solution would be to tag an SHA in the main job once it succeeds and then use this tag as a base. You can also try [using the devops CLI within the pipeline yaml](/recipes/ci/azure-last-successful-commit). See the [nx-tag-successful-ci-run](https://github.com/nrwl/nx-tag-successful-ci-run) and [nx-set-shas](https://github.com/nrwl/nx-set-shas) (version 1 implements tagging mechanism) repositories for more information. {% callout type="note" title="Tracking the origin branch" %} diff --git a/docs/shared/reference/sitemap.md b/docs/shared/reference/sitemap.md index 00974a9797dec..9c5f17bca2529 100644 --- a/docs/shared/reference/sitemap.md +++ b/docs/shared/reference/sitemap.md @@ -133,6 +133,7 @@ - [CI Setup](/recipes/ci/ci-setup) - [Prepare applications for deployment via CI](/recipes/ci/ci-deployment) - [Setting up Azure Pipelines](/recipes/ci/monorepo-ci-azure) + - [Find the Last Successful Commit in Azure Pipelines](/recipes/ci/azure-last-successful-commit) - [Setting up CircleCI](/recipes/ci/monorepo-ci-circle-ci) - [Setting up GitHub Actions](/recipes/ci/monorepo-ci-github-actions) - [Setting up Jenkins](/recipes/ci/monorepo-ci-jenkins) @@ -210,7 +211,6 @@ - [Using Tailwind CSS with Angular projects](/recipes/other/using-tailwind-css-with-angular-projects) - [Using NgRx](/recipes/other/misc-ngrx) - [Using Data Persistence operators](/recipes/other/misc-data-persistence) - - [Find the Last Successful Commit in Azure Pipelines](/recipes/other/azure-last-successful-commit) - [Troubleshoot Cache Misses](/recipes/other/troubleshoot-cache-misses) - [Export Project Graph](/recipes/other/export-project-graph) - [Resolve Circular Dependencies](/recipes/other/resolve-circular-dependencies) @@ -256,16 +256,15 @@ - [Access Tokens](/nx-cloud/account/access-tokens) - [Security Scenarios](/nx-cloud/account/scenarios) - [End to End Encryption](/nx-cloud/account/encryption) - - [On Prem](/nx-cloud/private-cloud) + - [Enterprise + On Prem](/nx-cloud/private-cloud) - [Get Started](/nx-cloud/private-cloud/get-started) - [Authenticate with a Single Admin](/nx-cloud/private-cloud/auth-single-admin) - [Authenticate with GitHub](/nx-cloud/private-cloud/auth-github) + - [On-Prem VM Setup](/nx-cloud/private-cloud/ami-setup) - [Authenticate with GitLab](/nx-cloud/private-cloud/auth-gitlab) - [Authenticate with BitBucket](/nx-cloud/private-cloud/auth-bitbucket) - [Authenticate via SAML](/nx-cloud/private-cloud/auth-saml) - [Advanced Configuration](/nx-cloud/private-cloud/advanced-config) - - [Kubernetes Setup](/nx-cloud/private-cloud/kubernetes-setup) - - [Standalone](/nx-cloud/private-cloud/standalone) - [Reference](/nx-cloud/reference) - [Configuration Options](/nx-cloud/reference/config) - [nx-cloud CLI](/nx-cloud/reference/nx-cloud-cli) diff --git a/nx-dev/nx-dev-e2e/src/e2e/nx-cloud-documentation.cy.ts b/nx-dev/nx-dev-e2e/src/e2e/nx-cloud-documentation.cy.ts index adac08ba2b22a..4a496882152cf 100644 --- a/nx-dev/nx-dev-e2e/src/e2e/nx-cloud-documentation.cy.ts +++ b/nx-dev/nx-dev-e2e/src/e2e/nx-cloud-documentation.cy.ts @@ -36,7 +36,7 @@ describe('nx-dev: Nx Cloud section', () => { path: '/nx-cloud/account/encryption', }, { - title: 'Running Nx Cloud on Prem', + title: 'Running Nx Cloud Enterprise', path: '/nx-cloud/private-cloud/get-started', }, { @@ -51,6 +51,10 @@ describe('nx-dev: Nx Cloud section', () => { title: 'GitLab Auth', path: '/nx-cloud/private-cloud/auth-gitlab', }, + { + title: 'Setting up a dedicated NxCloud VM', + path: '/nx-cloud/private-cloud/ami-setup', + }, { title: 'BitBucket Auth', path: '/nx-cloud/private-cloud/auth-bitbucket', diff --git a/nx-dev/nx-dev/redirect-rules.js b/nx-dev/nx-dev/redirect-rules.js index 414242945285c..5f52ad21c4e6a 100644 --- a/nx-dev/nx-dev/redirect-rules.js +++ b/nx-dev/nx-dev/redirect-rules.js @@ -351,6 +351,8 @@ const recipesUrls = { '/recipes/other/dte': '/recipes/example-repos/dte', '/recipes/other/deploy-nextjs-to-vercel': '/recipes/deployment/deploy-nextjs-to-vercel', + '/recipes/other/azure-last-successful-commit': + '/recipes/ci/azure-last-successful-commit', }; /** @@ -360,6 +362,9 @@ const nxCloudUrls = { '/nx-cloud/set-up/add-nx-cloud': '/core-features/share-your-cache', '/nx-cloud/set-up/set-up-caching': '/core-features/share-your-cache', '/nx-cloud/set-up/set-up-dte': '/core-features/distribute-task-execution', + '/nx-cloud/private-cloud/standalone': '/nx-cloud/private-cloud/ami-setup', + '/nx-cloud/private-cloud/kubernetes-setup': + '/nx-cloud/private-cloud/get-started', }; /** @@ -646,6 +651,10 @@ const pluginUrls = { '/recipes/generators/modifying-files': '/plugins/recipes/modifying-files', }; +const referenceUrls = { + '/changelog': '/reference/changelog', +}; + /** * Public export API */ @@ -664,4 +673,5 @@ module.exports = { conceptUrls, nested5minuteTutorialUrls, pluginUrls, + referenceUrls, };