zuplo 6.67.32 → 6.68.0

package/docs/articles/ci-cd-azure/multi-stage-deployment.mdx

@@ -0,0 +1,88 @@
+---
+title: "Azure Pipelines: Multi-Stage Deployment"
+sidebar_label: Multi-Stage Deployment
+---
+
+Deploy to staging, test, then promote to production with approval.
+
+```yaml title="azure-pipelines.yml"
+trigger:
+  - main
+
+pool:
+  vmImage: ubuntu-latest
+
+stages:
+  - stage: DeployStaging
+    displayName: "Deploy to Staging"
+    jobs:
+      - job: Deploy
+        steps:
+          - task: NodeTool@0
+            inputs:
+              versionSpec: "20.x"
+
+          - script: npm install
+
+          - script: |
+              set -o pipefail
+              npx zuplo deploy --api-key $(ZUPLO_API_KEY) --environment staging 2>&1 | tee ./STAGING_STDOUT
+              STAGING_URL=$(grep -oP 'Deployed to \K(https://[^ ]+)' ./STAGING_STDOUT)
+              echo "##vso[task.setvariable variable=STAGING_URL;isOutput=true]$STAGING_URL"
+            name: deployStep
+            displayName: "Deploy to staging"
+
+  - stage: TestStaging
+    displayName: "Test Staging"
+    dependsOn: DeployStaging
+    variables:
+      STAGING_URL:
+        $[
+        stageDependencies.DeployStaging.Deploy.outputs['deployStep.STAGING_URL']
+        ]
+    jobs:
+      - job: Test
+        steps:
+          - task: NodeTool@0
+            inputs:
+              versionSpec: "20.x"
+
+          - script: npm install
+
+          - script: npx zuplo test --endpoint $(STAGING_URL)
+            displayName: "Run tests against staging"
+
+  - stage: DeployProduction
+    displayName: "Deploy to Production"
+    dependsOn: TestStaging
+    jobs:
+      - deployment: Deploy
+        environment: production
+        strategy:
+          runOnce:
+            deploy:
+              steps:
+                - checkout: self
+
+                - task: NodeTool@0
+                  inputs:
+                    versionSpec: "20.x"
+
+                - script: npm install
+
+                - script:
+                    npx zuplo deploy --api-key $(ZUPLO_API_KEY) --environment
+                    production
+                  displayName: "Deploy to production"
+```
+
+## Setting Up Approval
+
+Create an environment with approval checks:
+
+1. Go to **Pipelines** > **Environments**
+2. Create an environment named `production`
+3. Add **Approvals and checks**
+4. Add required approvers
+
+The pipeline pauses before production deployment until approved.

package/docs/articles/ci-cd-azure/pr-preview-environments.mdx

@@ -0,0 +1,50 @@
+---
+title: "Azure Pipelines: PR Preview Environments"
+sidebar_label: PR Preview Environments
+---
+
+Deploy preview environments for pull requests and clean up when they close.
+
+```yaml title="azure-pipelines.yml"
+trigger:
+  - main
+
+pr:
+  - main
+
+pool:
+  vmImage: ubuntu-latest
+
+steps:
+  - task: NodeTool@0
+    inputs:
+      versionSpec: "20.x"
+    displayName: "Install Node.js"
+
+  - script: npm install
+    displayName: "Install dependencies"
+
+  - script: |
+      set -o pipefail
+      npx zuplo deploy --api-key $(ZUPLO_API_KEY) 2>&1 | tee ./DEPLOYMENT_STDOUT
+    displayName: "Deploy to Zuplo"
+
+  - script: |
+      DEPLOYMENT_URL=$(grep -oP 'Deployed to \K(https://[^ ]+)' ./DEPLOYMENT_STDOUT)
+      echo "##vso[task.setvariable variable=DEPLOYMENT_URL]$DEPLOYMENT_URL"
+      npx zuplo test --endpoint "$DEPLOYMENT_URL"
+    displayName: "Run tests"
+
+  - script: |
+      npx zuplo delete --url $(DEPLOYMENT_URL) --api-key $(ZUPLO_API_KEY) --wait
+    displayName: "Delete environment"
+    condition: eq(variables['Build.Reason'], 'PullRequest')
+```
+
+The cleanup step only runs for pull requests, deleting the preview environment
+after tests pass.
+
+## Next Steps
+
+- Implement [multi-stage deployment](./multi-stage-deployment.mdx) for
+  production

package/docs/articles/ci-cd-azure/tag-based-releases.mdx

@@ -0,0 +1,37 @@
+---
+title: "Azure Pipelines: Tag-Based Releases"
+sidebar_label: Tag-Based Releases
+---
+
+Deploy only when tags are pushed for controlled releases.
+
+```yaml title="azure-pipelines.yml"
+trigger:
+  tags:
+    include:
+      - v*
+
+pool:
+  vmImage: ubuntu-latest
+
+steps:
+  - task: NodeTool@0
+    inputs:
+      versionSpec: "20.x"
+    displayName: "Install Node.js"
+
+  - script: npm install
+    displayName: "Install dependencies"
+
+  - script: |
+      TAG_NAME=$(echo $(Build.SourceBranch) | sed 's|refs/tags/||')
+      npx zuplo deploy --api-key $(ZUPLO_API_KEY) --environment "$TAG_NAME"
+    displayName: "Deploy with tag name"
+```
+
+This pipeline triggers only on tags matching `v*` (like `v1.0.0`) and creates an
+environment named after the tag.
+
+## Next Steps
+
+- Add [multi-stage deployment](./multi-stage-deployment.mdx) with approval

package/docs/articles/ci-cd-bitbucket/basic-deployment.mdx

@@ -0,0 +1,27 @@
+---
+title: "Bitbucket Pipelines: Basic Deployment"
+sidebar_label: Basic Deployment
+---
+
+The simplest pipeline deploys your API to Zuplo on every push to main.
+
+```yaml title="bitbucket-pipelines.yml"
+image: node:20
+
+pipelines:
+  branches:
+    main:
+      - step:
+          name: Deploy to Zuplo
+          script:
+            - npm install
+            - npx zuplo deploy --api-key "$ZUPLO_API_KEY"
+```
+
+Store `ZUPLO_API_KEY` in **Repository settings** > **Pipelines** > **Repository
+variables**.
+
+## Next Steps
+
+- Add [automated testing](./deploy-and-test.mdx) after deployment
+- Set up [PR preview environments](./pr-preview-environments.mdx)

package/docs/articles/ci-cd-bitbucket/deploy-and-test.mdx

@@ -0,0 +1,41 @@
+---
+title: "Bitbucket Pipelines: Deploy and Test"
+sidebar_label: Deploy and Test
+---
+
+Run your test suite against the deployed environment to validate changes.
+
+```yaml title="bitbucket-pipelines.yml"
+image: node:20
+
+pipelines:
+  default:
+    - step:
+        name: Deploy to Zuplo
+        script:
+          - npm install
+          - npx zuplo deploy --api-key "$ZUPLO_API_KEY" 2>&1 | tee
+            ./DEPLOYMENT_STDOUT
+          - echo "DEPLOYMENT_URL=$(grep -oP 'Deployed to \K(https://[^ ]+)'
+            ./DEPLOYMENT_STDOUT)" >> deployment.env
+        artifacts:
+          - deployment.env
+
+    - step:
+        name: Run Tests
+        script:
+          - source deployment.env
+          - npm install
+          - npx zuplo test --endpoint "$DEPLOYMENT_URL"
+```
+
+This pipeline:
+
+1. Deploys to Zuplo and captures the output
+2. Extracts the deployment URL and saves it as an artifact
+3. Runs tests against the deployed environment
+
+## Next Steps
+
+- Add [PR preview environments](./pr-preview-environments.mdx) with cleanup
+- Run [local tests](./local-testing.mdx) before deploying

package/docs/articles/ci-cd-bitbucket/local-testing.mdx

@@ -0,0 +1,34 @@
+---
+title: "Bitbucket Pipelines: Local Testing in CI"
+sidebar_label: Local Testing in CI
+---
+
+Test against a local Zuplo server before deploying anywhere.
+
+```yaml title="bitbucket-pipelines.yml"
+image: node:20
+
+pipelines:
+  branches:
+    main:
+      - step:
+          name: Local Testing
+          script:
+            - npm install
+            - npx zuplo dev &
+            - sleep 10
+            - npx zuplo test --endpoint http://localhost:9000
+            - kill %1
+
+      - step:
+          name: Deploy to Zuplo
+          script:
+            - npm install
+            - npx zuplo deploy --api-key "$ZUPLO_API_KEY"
+```
+
+Local tests run first. Only if they pass does deployment proceed.
+
+## Next Steps
+
+- Add [multi-stage deployment](./multi-stage-deployment.mdx) with staging

package/docs/articles/ci-cd-bitbucket/multi-stage-deployment.mdx

@@ -0,0 +1,52 @@
+---
+title: "Bitbucket Pipelines: Multi-Stage Deployment"
+sidebar_label: Multi-Stage Deployment
+---
+
+Deploy to staging, test, then promote to production with approval.
+
+```yaml title="bitbucket-pipelines.yml"
+image: node:20
+
+pipelines:
+  branches:
+    main:
+      - step:
+          name: Deploy to Staging
+          script:
+            - npm install
+            - npx zuplo deploy --api-key "$ZUPLO_API_KEY" --environment staging
+              2>&1 | tee ./DEPLOYMENT_STDOUT
+            - echo "STAGING_URL=$(grep -oP 'Deployed to \K(https://[^ ]+)'
+              ./DEPLOYMENT_STDOUT)" >> staging.env
+          artifacts:
+            - staging.env
+
+      - step:
+          name: Test Staging
+          script:
+            - source staging.env
+            - npm install
+            - npx zuplo test --endpoint "$STAGING_URL"
+
+      - step:
+          name: Deploy to Production
+          trigger: manual
+          deployment: production
+          script:
+            - npm install
+            - npx zuplo deploy --api-key "$ZUPLO_API_KEY" --environment
+              production
+```
+
+## Setting Up Approval
+
+The `trigger: manual` setting requires someone to click "Run" in the Bitbucket
+UI to trigger production deployment.
+
+For more control, use
+[Deployment permissions](https://support.atlassian.com/bitbucket-cloud/docs/set-up-and-monitor-deployments/):
+
+1. Go to **Repository settings** > **Deployments**
+2. Create a `production` deployment environment
+3. Add required reviewers under **Deployment restrictions**

package/docs/articles/ci-cd-bitbucket/pr-preview-environments.mdx

@@ -0,0 +1,46 @@
+---
+title: "Bitbucket Pipelines: PR Preview Environments"
+sidebar_label: PR Preview Environments
+---
+
+Deploy preview environments for pull requests and clean up when they close.
+
+```yaml title="bitbucket-pipelines.yml"
+image: node:20
+
+pipelines:
+  pull-requests:
+    "**":
+      - step:
+          name: Deploy Preview
+          script:
+            - npm install
+            - npx zuplo deploy --api-key "$ZUPLO_API_KEY" 2>&1 | tee
+              ./DEPLOYMENT_STDOUT
+            - echo "DEPLOYMENT_URL=$(grep -oP 'Deployed to \K(https://[^ ]+)'
+              ./DEPLOYMENT_STDOUT)" >> deployment.env
+          artifacts:
+            - deployment.env
+
+      - step:
+          name: Run Tests
+          script:
+            - source deployment.env
+            - npm install
+            - npx zuplo test --endpoint "$DEPLOYMENT_URL"
+
+      - step:
+          name: Cleanup Preview
+          script:
+            - source deployment.env
+            - npm install
+            - npx zuplo delete --url "$DEPLOYMENT_URL" --api-key
+              "$ZUPLO_API_KEY" --wait
+```
+
+The cleanup step runs after tests complete, deleting the preview environment.
+
+## Next Steps
+
+- Implement [multi-stage deployment](./multi-stage-deployment.mdx) for
+  production

package/docs/articles/ci-cd-bitbucket/tag-based-releases.mdx

@@ -0,0 +1,27 @@
+---
+title: "Bitbucket Pipelines: Tag-Based Releases"
+sidebar_label: Tag-Based Releases
+---
+
+Deploy only when tags are pushed for controlled releases.
+
+```yaml title="bitbucket-pipelines.yml"
+image: node:20
+
+pipelines:
+  tags:
+    v*:
+      - step:
+          name: Deploy Release
+          script:
+            - npm install
+            - npx zuplo deploy --api-key "$ZUPLO_API_KEY" --environment
+              "$BITBUCKET_TAG"
+```
+
+This pipeline triggers only on tags matching `v*` (like `v1.0.0`) and creates an
+environment named after the tag.
+
+## Next Steps
+
+- Add [multi-stage deployment](./multi-stage-deployment.mdx) with approval

package/docs/articles/ci-cd-circleci/basic-deployment.mdx

@@ -0,0 +1,34 @@
+---
+title: "CircleCI: Basic Deployment"
+sidebar_label: Basic Deployment
+---
+
+The simplest workflow deploys your API to Zuplo on every push to main.
+
+```yaml title=".circleci/config.yml"
+version: 2.1
+
+jobs:
+  deploy:
+    docker:
+      - image: cimg/node:20.0
+    steps:
+      - checkout
+      - run: npm install
+      - run: npx zuplo deploy --api-key "$ZUPLO_API_KEY"
+
+workflows:
+  deploy:
+    jobs:
+      - deploy:
+          filters:
+            branches:
+              only: main
+```
+
+Store `ZUPLO_API_KEY` in **Project Settings** > **Environment Variables**.
+
+## Next Steps
+
+- Add [automated testing](./deploy-and-test.mdx) after deployment
+- Set up [PR preview environments](./pr-preview-environments.mdx)

package/docs/articles/ci-cd-circleci/deploy-and-test.mdx

@@ -0,0 +1,44 @@
+---
+title: "CircleCI: Deploy and Test"
+sidebar_label: Deploy and Test
+---
+
+Run your test suite against the deployed environment to validate changes.
+
+```yaml title=".circleci/config.yml"
+version: 2.1
+
+jobs:
+  deploy:
+    docker:
+      - image: cimg/node:20.0
+    steps:
+      - checkout
+      - run: npm install
+      - run:
+          name: Deploy to Zuplo
+          command: |
+            set -o pipefail
+            npx zuplo deploy --api-key "$ZUPLO_API_KEY" 2>&1 | tee ./DEPLOYMENT_STDOUT
+            DEPLOYMENT_URL=$(grep -oP 'Deployed to \K(https://[^ ]+)' ./DEPLOYMENT_STDOUT)
+            echo "export DEPLOYMENT_URL=$DEPLOYMENT_URL" >> "$BASH_ENV"
+      - run:
+          name: Run Tests
+          command: npx zuplo test --endpoint "$DEPLOYMENT_URL"
+
+workflows:
+  deploy-and-test:
+    jobs:
+      - deploy
+```
+
+This workflow:
+
+1. Deploys to Zuplo and captures the output
+2. Extracts the deployment URL
+3. Runs tests against the deployed environment
+
+## Next Steps
+
+- Add [PR preview environments](./pr-preview-environments.mdx) with cleanup
+- Run [local tests](./local-testing.mdx) before deploying

package/docs/articles/ci-cd-circleci/local-testing.mdx

@@ -0,0 +1,50 @@
+---
+title: "CircleCI: Local Testing in CI"
+sidebar_label: Local Testing in CI
+---
+
+Test against a local Zuplo server before deploying anywhere.
+
+```yaml title=".circleci/config.yml"
+version: 2.1
+
+jobs:
+  local-test:
+    docker:
+      - image: cimg/node:20.0
+    steps:
+      - checkout
+      - run: npm install
+      - run:
+          name: Start local server and run tests
+          command: |
+            npx zuplo dev &
+            sleep 10
+            npx zuplo test --endpoint http://localhost:9000
+            kill %1
+
+  deploy:
+    docker:
+      - image: cimg/node:20.0
+    steps:
+      - checkout
+      - run: npm install
+      - run: npx zuplo deploy --api-key "$ZUPLO_API_KEY"
+
+workflows:
+  test-and-deploy:
+    jobs:
+      - local-test
+      - deploy:
+          requires:
+            - local-test
+          filters:
+            branches:
+              only: main
+```
+
+Local tests run first. Only if they pass does deployment proceed.
+
+## Next Steps
+
+- Add [multi-stage deployment](./multi-stage-deployment.mdx) with staging

package/docs/articles/ci-cd-circleci/multi-stage-deployment.mdx

@@ -0,0 +1,82 @@
+---
+title: "CircleCI: Multi-Stage Deployment"
+sidebar_label: Multi-Stage Deployment
+---
+
+Deploy to staging, test, then promote to production with approval.
+
+```yaml title=".circleci/config.yml"
+version: 2.1
+
+jobs:
+  deploy-staging:
+    docker:
+      - image: cimg/node:20.0
+    steps:
+      - checkout
+      - run: npm install
+      - run:
+          name: Deploy to Staging
+          command: |
+            set -o pipefail
+            npx zuplo deploy --api-key "$ZUPLO_API_KEY" --environment staging 2>&1 | tee ./DEPLOYMENT_STDOUT
+            STAGING_URL=$(grep -oP 'Deployed to \K(https://[^ ]+)' ./DEPLOYMENT_STDOUT)
+            echo "export STAGING_URL=$STAGING_URL" >> "$BASH_ENV"
+            echo "$STAGING_URL" > staging_url.txt
+      - persist_to_workspace:
+          root: .
+          paths:
+            - staging_url.txt
+
+  test-staging:
+    docker:
+      - image: cimg/node:20.0
+    steps:
+      - checkout
+      - attach_workspace:
+          at: .
+      - run: npm install
+      - run:
+          name: Run Tests
+          command: |
+            STAGING_URL=$(cat staging_url.txt)
+            npx zuplo test --endpoint "$STAGING_URL"
+
+  deploy-production:
+    docker:
+      - image: cimg/node:20.0
+    steps:
+      - checkout
+      - run: npm install
+      - run:
+          npx zuplo deploy --api-key "$ZUPLO_API_KEY" --environment production
+
+workflows:
+  staging-to-production:
+    jobs:
+      - deploy-staging:
+          filters:
+            branches:
+              only: main
+      - test-staging:
+          requires:
+            - deploy-staging
+      - hold-for-approval:
+          type: approval
+          requires:
+            - test-staging
+      - deploy-production:
+          requires:
+            - hold-for-approval
+```
+
+## Setting Up Approval
+
+The `type: approval` job pauses the workflow until someone approves it in the
+CircleCI UI.
+
+For more control:
+
+1. Go to **Project Settings** > **Advanced**
+2. Enable **Only build pull requests** for protected branches
+3. Use CircleCI contexts to restrict who can approve production deployments

package/docs/articles/ci-cd-circleci/pr-preview-environments.mdx

@@ -0,0 +1,47 @@
+---
+title: "CircleCI: PR Preview Environments"
+sidebar_label: PR Preview Environments
+---
+
+Deploy preview environments for pull requests and clean up after tests.
+
+```yaml title=".circleci/config.yml"
+version: 2.1
+
+jobs:
+  deploy-and-test:
+    docker:
+      - image: cimg/node:20.0
+    steps:
+      - checkout
+      - run: npm install
+      - run:
+          name: Deploy to Zuplo
+          command: |
+            set -o pipefail
+            npx zuplo deploy --api-key "$ZUPLO_API_KEY" 2>&1 | tee ./DEPLOYMENT_STDOUT
+            DEPLOYMENT_URL=$(grep -oP 'Deployed to \K(https://[^ ]+)' ./DEPLOYMENT_STDOUT)
+            echo "export DEPLOYMENT_URL=$DEPLOYMENT_URL" >> "$BASH_ENV"
+      - run:
+          name: Run Tests
+          command: npx zuplo test --endpoint "$DEPLOYMENT_URL"
+      - run:
+          name: Cleanup Preview
+          command:
+            npx zuplo delete --url "$DEPLOYMENT_URL" --api-key "$ZUPLO_API_KEY"
+            --wait
+          when: always
+
+workflows:
+  preview:
+    jobs:
+      - deploy-and-test
+```
+
+The cleanup step runs after tests complete (whether they pass or fail), deleting
+the preview environment.
+
+## Next Steps
+
+- Implement [multi-stage deployment](./multi-stage-deployment.mdx) for
+  production