From 161efc29218e8744385759ce84585ec95c0adb79 Mon Sep 17 00:00:00 2001 From: Dawson Toth Date: Mon, 13 Jul 2026 16:38:11 -0400 Subject: [PATCH 1/3] feat: scaffold deploy-by-reference using the native harper CLI MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Templates deploy by *reference* (the Harper cluster clones a pinned commit over SSH) with no per-project scripts: deploy -> `harper deploy by_ref=true restart=true replicated=true`, deploy:setup -> `harper deploy setup=true`. Centralized GitHub Actions workflow (.github/workflows/deploy.yaml — also fixes the singular workflow/ -> workflows/ path bug so GitHub runs it); tag+dispatch triggered. .env carries only CLI_TARGET (creds via harper login / CI secrets). README deployment sections rewritten around the reference model. End-state assuming native CLI support has landed: harper#1777 (by_ref), harper#1778 (deploy setup), harper-pro#570 (add_ssh_key generate). Tracks create-harper#117. DRAFT until those release. Co-Authored-By: Claude Opus 4.8 --- .../_github/workflows/deploy.yaml | 53 +++++++++++++++++++ template-react-ssr/README.md | 39 ++++++++++++-- .../_github/workflow/deploy.yaml | 33 ------------ .../_github/workflows/deploy.yaml | 53 +++++++++++++++++++ template-react-ssr/package.json | 3 +- template-react-ts-ssr/README.md | 39 ++++++++++++-- .../_github/workflow/deploy.yaml | 33 ------------ .../_github/workflows/deploy.yaml | 53 +++++++++++++++++++ template-react-ts-ssr/package.json | 3 +- template-react-ts/README.md | 39 ++++++++++++-- .../_github/workflow/deploy.yaml | 33 ------------ .../_github/workflows/deploy.yaml | 53 +++++++++++++++++++ template-react-ts/package.json | 3 +- template-react/README.md | 39 ++++++++++++-- template-react/_github/workflow/deploy.yaml | 33 ------------ template-react/_github/workflows/deploy.yaml | 53 +++++++++++++++++++ template-react/package.json | 3 +- template-vanilla-ts/README.md | 39 ++++++++++++-- .../_github/workflow/deploy.yaml | 33 ------------ .../_github/workflows/deploy.yaml | 53 +++++++++++++++++++ template-vanilla-ts/package.json | 3 +- template-vanilla/README.md | 39 ++++++++++++-- template-vanilla/_github/workflow/deploy.yaml | 33 ------------ .../_github/workflows/deploy.yaml | 53 +++++++++++++++++++ template-vanilla/package.json | 3 +- template-vue-ssr/README.md | 39 ++++++++++++-- template-vue-ssr/_github/workflow/deploy.yaml | 33 ------------ .../_github/workflows/deploy.yaml | 53 +++++++++++++++++++ template-vue-ssr/package.json | 3 +- template-vue-ts-ssr/README.md | 39 ++++++++++++-- .../_github/workflow/deploy.yaml | 33 ------------ .../_github/workflows/deploy.yaml | 53 +++++++++++++++++++ template-vue-ts-ssr/package.json | 3 +- template-vue-ts/README.md | 39 ++++++++++++-- template-vue-ts/_github/workflow/deploy.yaml | 33 ------------ template-vue-ts/_github/workflows/deploy.yaml | 53 +++++++++++++++++++ template-vue-ts/package.json | 3 +- template-vue/README.md | 39 ++++++++++++-- template-vue/_github/workflow/deploy.yaml | 33 ------------ template-vue/_github/workflows/deploy.yaml | 53 +++++++++++++++++++ template-vue/package.json | 3 +- template.tests/template.test.js | 14 ++++- .../all/_github/workflows/deploy.yaml | 53 +++++++++++++++++++ 43 files changed, 1028 insertions(+), 372 deletions(-) create mode 100644 template-early-hints/_github/workflows/deploy.yaml delete mode 100644 template-react-ssr/_github/workflow/deploy.yaml create mode 100644 template-react-ssr/_github/workflows/deploy.yaml delete mode 100644 template-react-ts-ssr/_github/workflow/deploy.yaml create mode 100644 template-react-ts-ssr/_github/workflows/deploy.yaml delete mode 100644 template-react-ts/_github/workflow/deploy.yaml create mode 100644 template-react-ts/_github/workflows/deploy.yaml delete mode 100644 template-react/_github/workflow/deploy.yaml create mode 100644 template-react/_github/workflows/deploy.yaml delete mode 100644 template-vanilla-ts/_github/workflow/deploy.yaml create mode 100644 template-vanilla-ts/_github/workflows/deploy.yaml delete mode 100644 template-vanilla/_github/workflow/deploy.yaml create mode 100644 template-vanilla/_github/workflows/deploy.yaml delete mode 100644 template-vue-ssr/_github/workflow/deploy.yaml create mode 100644 template-vue-ssr/_github/workflows/deploy.yaml delete mode 100644 template-vue-ts-ssr/_github/workflow/deploy.yaml create mode 100644 template-vue-ts-ssr/_github/workflows/deploy.yaml delete mode 100644 template-vue-ts/_github/workflow/deploy.yaml create mode 100644 template-vue-ts/_github/workflows/deploy.yaml delete mode 100644 template-vue/_github/workflow/deploy.yaml create mode 100644 template-vue/_github/workflows/deploy.yaml create mode 100644 templates-shared/all/_github/workflows/deploy.yaml diff --git a/template-early-hints/_github/workflows/deploy.yaml b/template-early-hints/_github/workflows/deploy.yaml new file mode 100644 index 0000000..5b7ef1a --- /dev/null +++ b/template-early-hints/_github/workflows/deploy.yaml @@ -0,0 +1,53 @@ +# Deploys this app to your Harper cluster by *reference* via `harper deploy by_ref=true` +# (`npm run deploy`). +# +# Runs on a version tag (e.g. `git tag v1.2.3 && git push --tags`) or manually. The Harper cluster +# fetches the tagged commit over SSH (pinned by its exact SHA, so peers can't diverge on a moved tag) +# using the read-only deploy key you registered once with `npm run deploy:setup`. +# +# Required repository secrets (Settings → Secrets and variables → Actions): +# CLI_TARGET your cluster's operations URL, e.g. https://my-cluster.harperdb.io:9925 +# HARPER_CLI_USERNAME a cluster user allowed to deploy +# HARPER_CLI_PASSWORD that user's password +# +# Public repo and want zero cluster-side auth, or prefer building in CI and publishing to a registry? +# See the "Deployment" section of the README for those alternatives. +name: Deploy to Harper Fabric +on: + workflow_dispatch: + push: + tags: + - 'v*' + +concurrency: + group: deploy + cancel-in-progress: false + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1 + with: + fetch-depth: 0 + fetch-tags: true + - name: Set up Node.js + uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0 + with: + cache: 'npm' + node-version-file: '.nvmrc' + - name: Install dependencies + run: npm ci + - name: Run unit tests + run: npm test + - name: Run lint + run: npm run lint + - name: Install Harper CLI + run: npm install -g harper + - name: Deploy + run: npm run deploy + env: + CLI_TARGET: ${{ secrets.CLI_TARGET }} + HARPER_CLI_USERNAME: ${{ secrets.HARPER_CLI_USERNAME }} + HARPER_CLI_PASSWORD: ${{ secrets.HARPER_CLI_PASSWORD }} diff --git a/template-react-ssr/README.md b/template-react-ssr/README.md index f31ffcd..893ffe2 100644 --- a/template-react-ssr/README.md +++ b/template-react-ssr/README.md @@ -103,20 +103,53 @@ Take a look at the [default configuration](./config.yaml), which specifies how f ## Deployment -When you are ready, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in to your account, and create a cluster. +Deploy your app to a Harper cluster **by reference**: rather than uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit. -Come back and log in your local CLI to your cluster: +First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in, and create a cluster. Then log your local CLI in to it: ```sh harper login ``` -Then you can deploy your app to your cluster: +### One-time setup + +So the cluster can clone your (private) repository, register a read-only SSH **deploy key**: + +```sh +npm run deploy:setup +``` + +This generates the key, registers it with your cluster, and prints a public key to add to your repository under **Settings → Deploy keys**. A deploy key is scoped to this one repository and keeps working even if the person who created it leaves. (It uses Harper's `add_ssh_key`, available on Harper Pro / Fabric.) + +### Deploy ```sh npm run deploy ``` +This deploys the current commit — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again. + +### Deploy automatically from CI + +The included [GitHub Actions workflow](./.github/workflows/deploy.yaml) deploys whenever you push a version tag: + +```sh +git tag v1.0.0 +git push --tags +``` + +Add these repository secrets first, under **Settings → Secrets and variables → Actions**: + +- `CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`) +- `HARPER_CLI_USERNAME` and `HARPER_CLI_PASSWORD` — a cluster user allowed to deploy + +### Other options + +- **Public repository?** Skip the deploy key and let Harper clone over HTTPS (`git+https://…#`) with no cluster-side credentials. +- **Prefer to build in CI** instead of on your Harper nodes? Publish your app to a registry such as GitHub Packages and deploy it by version using `registryAuth`. + +See the [Harper deployment docs](https://docs.harperdb.io/reference/v5/components/applications#deploy_component) for both. + ## Keep Going! For more information about getting started with Harper and building applications, see our [getting started guide](https://docs.harperdb.io/docs). diff --git a/template-react-ssr/_github/workflow/deploy.yaml b/template-react-ssr/_github/workflow/deploy.yaml deleted file mode 100644 index cc5039e..0000000 --- a/template-react-ssr/_github/workflow/deploy.yaml +++ /dev/null @@ -1,33 +0,0 @@ -name: Deploy to Harper Fabric -on: - workflow_dispatch: -# push: -# branches: -# - main - -concurrency: - group: main - cancel-in-progress: false - -jobs: - deploy: - runs-on: ubuntu-latest - steps: - - name: Checkout code - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1 - with: - fetch-depth: 0 - fetch-tags: true - - name: Set up Node.js - uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0 - with: - cache: 'npm' - node-version-file: '.nvmrc' - - name: Install dependencies - run: npm ci - - name: Run unit tests - run: npm test - - name: Run lint - run: npm run lint - - name: Build & deploy - run: npm run deploy diff --git a/template-react-ssr/_github/workflows/deploy.yaml b/template-react-ssr/_github/workflows/deploy.yaml new file mode 100644 index 0000000..5b7ef1a --- /dev/null +++ b/template-react-ssr/_github/workflows/deploy.yaml @@ -0,0 +1,53 @@ +# Deploys this app to your Harper cluster by *reference* via `harper deploy by_ref=true` +# (`npm run deploy`). +# +# Runs on a version tag (e.g. `git tag v1.2.3 && git push --tags`) or manually. The Harper cluster +# fetches the tagged commit over SSH (pinned by its exact SHA, so peers can't diverge on a moved tag) +# using the read-only deploy key you registered once with `npm run deploy:setup`. +# +# Required repository secrets (Settings → Secrets and variables → Actions): +# CLI_TARGET your cluster's operations URL, e.g. https://my-cluster.harperdb.io:9925 +# HARPER_CLI_USERNAME a cluster user allowed to deploy +# HARPER_CLI_PASSWORD that user's password +# +# Public repo and want zero cluster-side auth, or prefer building in CI and publishing to a registry? +# See the "Deployment" section of the README for those alternatives. +name: Deploy to Harper Fabric +on: + workflow_dispatch: + push: + tags: + - 'v*' + +concurrency: + group: deploy + cancel-in-progress: false + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1 + with: + fetch-depth: 0 + fetch-tags: true + - name: Set up Node.js + uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0 + with: + cache: 'npm' + node-version-file: '.nvmrc' + - name: Install dependencies + run: npm ci + - name: Run unit tests + run: npm test + - name: Run lint + run: npm run lint + - name: Install Harper CLI + run: npm install -g harper + - name: Deploy + run: npm run deploy + env: + CLI_TARGET: ${{ secrets.CLI_TARGET }} + HARPER_CLI_USERNAME: ${{ secrets.HARPER_CLI_USERNAME }} + HARPER_CLI_PASSWORD: ${{ secrets.HARPER_CLI_PASSWORD }} diff --git a/template-react-ssr/package.json b/template-react-ssr/package.json index a6314da..6ded932 100644 --- a/template-react-ssr/package.json +++ b/template-react-ssr/package.json @@ -13,7 +13,8 @@ "test": "node --test test/*.test.js", "test:watch": "node --watch --test test/*.test.js", "build": "vite build", - "deploy": "harper deploy_component . restart=true replicated=true" + "deploy": "harper deploy by_ref=true restart=true replicated=true", + "deploy:setup": "harper deploy setup=true" }, "dependencies": { "@harperfast/schema-codegen": "^1.0.10", diff --git a/template-react-ts-ssr/README.md b/template-react-ts-ssr/README.md index 90bc495..9af4e5f 100644 --- a/template-react-ts-ssr/README.md +++ b/template-react-ts-ssr/README.md @@ -111,20 +111,53 @@ Take a look at the [default configuration](./config.yaml), which specifies how f ## Deployment -When you are ready, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in to your account, and create a cluster. +Deploy your app to a Harper cluster **by reference**: rather than uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit. -Come back and log in your local CLI to your cluster: +First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in, and create a cluster. Then log your local CLI in to it: ```sh harper login ``` -Then you can deploy your app to your cluster: +### One-time setup + +So the cluster can clone your (private) repository, register a read-only SSH **deploy key**: + +```sh +npm run deploy:setup +``` + +This generates the key, registers it with your cluster, and prints a public key to add to your repository under **Settings → Deploy keys**. A deploy key is scoped to this one repository and keeps working even if the person who created it leaves. (It uses Harper's `add_ssh_key`, available on Harper Pro / Fabric.) + +### Deploy ```sh npm run deploy ``` +This deploys the current commit — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again. + +### Deploy automatically from CI + +The included [GitHub Actions workflow](./.github/workflows/deploy.yaml) deploys whenever you push a version tag: + +```sh +git tag v1.0.0 +git push --tags +``` + +Add these repository secrets first, under **Settings → Secrets and variables → Actions**: + +- `CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`) +- `HARPER_CLI_USERNAME` and `HARPER_CLI_PASSWORD` — a cluster user allowed to deploy + +### Other options + +- **Public repository?** Skip the deploy key and let Harper clone over HTTPS (`git+https://…#`) with no cluster-side credentials. +- **Prefer to build in CI** instead of on your Harper nodes? Publish your app to a registry such as GitHub Packages and deploy it by version using `registryAuth`. + +See the [Harper deployment docs](https://docs.harperdb.io/reference/v5/components/applications#deploy_component) for both. + ## Keep Going! For more information about getting started with Harper and building applications, see our [getting started guide](https://docs.harperdb.io/docs). diff --git a/template-react-ts-ssr/_github/workflow/deploy.yaml b/template-react-ts-ssr/_github/workflow/deploy.yaml deleted file mode 100644 index cc5039e..0000000 --- a/template-react-ts-ssr/_github/workflow/deploy.yaml +++ /dev/null @@ -1,33 +0,0 @@ -name: Deploy to Harper Fabric -on: - workflow_dispatch: -# push: -# branches: -# - main - -concurrency: - group: main - cancel-in-progress: false - -jobs: - deploy: - runs-on: ubuntu-latest - steps: - - name: Checkout code - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1 - with: - fetch-depth: 0 - fetch-tags: true - - name: Set up Node.js - uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0 - with: - cache: 'npm' - node-version-file: '.nvmrc' - - name: Install dependencies - run: npm ci - - name: Run unit tests - run: npm test - - name: Run lint - run: npm run lint - - name: Build & deploy - run: npm run deploy diff --git a/template-react-ts-ssr/_github/workflows/deploy.yaml b/template-react-ts-ssr/_github/workflows/deploy.yaml new file mode 100644 index 0000000..5b7ef1a --- /dev/null +++ b/template-react-ts-ssr/_github/workflows/deploy.yaml @@ -0,0 +1,53 @@ +# Deploys this app to your Harper cluster by *reference* via `harper deploy by_ref=true` +# (`npm run deploy`). +# +# Runs on a version tag (e.g. `git tag v1.2.3 && git push --tags`) or manually. The Harper cluster +# fetches the tagged commit over SSH (pinned by its exact SHA, so peers can't diverge on a moved tag) +# using the read-only deploy key you registered once with `npm run deploy:setup`. +# +# Required repository secrets (Settings → Secrets and variables → Actions): +# CLI_TARGET your cluster's operations URL, e.g. https://my-cluster.harperdb.io:9925 +# HARPER_CLI_USERNAME a cluster user allowed to deploy +# HARPER_CLI_PASSWORD that user's password +# +# Public repo and want zero cluster-side auth, or prefer building in CI and publishing to a registry? +# See the "Deployment" section of the README for those alternatives. +name: Deploy to Harper Fabric +on: + workflow_dispatch: + push: + tags: + - 'v*' + +concurrency: + group: deploy + cancel-in-progress: false + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1 + with: + fetch-depth: 0 + fetch-tags: true + - name: Set up Node.js + uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0 + with: + cache: 'npm' + node-version-file: '.nvmrc' + - name: Install dependencies + run: npm ci + - name: Run unit tests + run: npm test + - name: Run lint + run: npm run lint + - name: Install Harper CLI + run: npm install -g harper + - name: Deploy + run: npm run deploy + env: + CLI_TARGET: ${{ secrets.CLI_TARGET }} + HARPER_CLI_USERNAME: ${{ secrets.HARPER_CLI_USERNAME }} + HARPER_CLI_PASSWORD: ${{ secrets.HARPER_CLI_PASSWORD }} diff --git a/template-react-ts-ssr/package.json b/template-react-ts-ssr/package.json index 516a760..43d00e6 100644 --- a/template-react-ts-ssr/package.json +++ b/template-react-ts-ssr/package.json @@ -13,7 +13,8 @@ "test": "node --test test/*.test.ts", "test:watch": "node --watch --test test/*.test.ts", "build": "vite build", - "deploy": "harper deploy_component . restart=true replicated=true" + "deploy": "harper deploy by_ref=true restart=true replicated=true", + "deploy:setup": "harper deploy setup=true" }, "dependencies": { "@harperfast/schema-codegen": "^1.0.10", diff --git a/template-react-ts/README.md b/template-react-ts/README.md index 90bc495..9af4e5f 100644 --- a/template-react-ts/README.md +++ b/template-react-ts/README.md @@ -111,20 +111,53 @@ Take a look at the [default configuration](./config.yaml), which specifies how f ## Deployment -When you are ready, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in to your account, and create a cluster. +Deploy your app to a Harper cluster **by reference**: rather than uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit. -Come back and log in your local CLI to your cluster: +First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in, and create a cluster. Then log your local CLI in to it: ```sh harper login ``` -Then you can deploy your app to your cluster: +### One-time setup + +So the cluster can clone your (private) repository, register a read-only SSH **deploy key**: + +```sh +npm run deploy:setup +``` + +This generates the key, registers it with your cluster, and prints a public key to add to your repository under **Settings → Deploy keys**. A deploy key is scoped to this one repository and keeps working even if the person who created it leaves. (It uses Harper's `add_ssh_key`, available on Harper Pro / Fabric.) + +### Deploy ```sh npm run deploy ``` +This deploys the current commit — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again. + +### Deploy automatically from CI + +The included [GitHub Actions workflow](./.github/workflows/deploy.yaml) deploys whenever you push a version tag: + +```sh +git tag v1.0.0 +git push --tags +``` + +Add these repository secrets first, under **Settings → Secrets and variables → Actions**: + +- `CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`) +- `HARPER_CLI_USERNAME` and `HARPER_CLI_PASSWORD` — a cluster user allowed to deploy + +### Other options + +- **Public repository?** Skip the deploy key and let Harper clone over HTTPS (`git+https://…#`) with no cluster-side credentials. +- **Prefer to build in CI** instead of on your Harper nodes? Publish your app to a registry such as GitHub Packages and deploy it by version using `registryAuth`. + +See the [Harper deployment docs](https://docs.harperdb.io/reference/v5/components/applications#deploy_component) for both. + ## Keep Going! For more information about getting started with Harper and building applications, see our [getting started guide](https://docs.harperdb.io/docs). diff --git a/template-react-ts/_github/workflow/deploy.yaml b/template-react-ts/_github/workflow/deploy.yaml deleted file mode 100644 index cc5039e..0000000 --- a/template-react-ts/_github/workflow/deploy.yaml +++ /dev/null @@ -1,33 +0,0 @@ -name: Deploy to Harper Fabric -on: - workflow_dispatch: -# push: -# branches: -# - main - -concurrency: - group: main - cancel-in-progress: false - -jobs: - deploy: - runs-on: ubuntu-latest - steps: - - name: Checkout code - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1 - with: - fetch-depth: 0 - fetch-tags: true - - name: Set up Node.js - uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0 - with: - cache: 'npm' - node-version-file: '.nvmrc' - - name: Install dependencies - run: npm ci - - name: Run unit tests - run: npm test - - name: Run lint - run: npm run lint - - name: Build & deploy - run: npm run deploy diff --git a/template-react-ts/_github/workflows/deploy.yaml b/template-react-ts/_github/workflows/deploy.yaml new file mode 100644 index 0000000..5b7ef1a --- /dev/null +++ b/template-react-ts/_github/workflows/deploy.yaml @@ -0,0 +1,53 @@ +# Deploys this app to your Harper cluster by *reference* via `harper deploy by_ref=true` +# (`npm run deploy`). +# +# Runs on a version tag (e.g. `git tag v1.2.3 && git push --tags`) or manually. The Harper cluster +# fetches the tagged commit over SSH (pinned by its exact SHA, so peers can't diverge on a moved tag) +# using the read-only deploy key you registered once with `npm run deploy:setup`. +# +# Required repository secrets (Settings → Secrets and variables → Actions): +# CLI_TARGET your cluster's operations URL, e.g. https://my-cluster.harperdb.io:9925 +# HARPER_CLI_USERNAME a cluster user allowed to deploy +# HARPER_CLI_PASSWORD that user's password +# +# Public repo and want zero cluster-side auth, or prefer building in CI and publishing to a registry? +# See the "Deployment" section of the README for those alternatives. +name: Deploy to Harper Fabric +on: + workflow_dispatch: + push: + tags: + - 'v*' + +concurrency: + group: deploy + cancel-in-progress: false + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1 + with: + fetch-depth: 0 + fetch-tags: true + - name: Set up Node.js + uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0 + with: + cache: 'npm' + node-version-file: '.nvmrc' + - name: Install dependencies + run: npm ci + - name: Run unit tests + run: npm test + - name: Run lint + run: npm run lint + - name: Install Harper CLI + run: npm install -g harper + - name: Deploy + run: npm run deploy + env: + CLI_TARGET: ${{ secrets.CLI_TARGET }} + HARPER_CLI_USERNAME: ${{ secrets.HARPER_CLI_USERNAME }} + HARPER_CLI_PASSWORD: ${{ secrets.HARPER_CLI_PASSWORD }} diff --git a/template-react-ts/package.json b/template-react-ts/package.json index 516a760..43d00e6 100644 --- a/template-react-ts/package.json +++ b/template-react-ts/package.json @@ -13,7 +13,8 @@ "test": "node --test test/*.test.ts", "test:watch": "node --watch --test test/*.test.ts", "build": "vite build", - "deploy": "harper deploy_component . restart=true replicated=true" + "deploy": "harper deploy by_ref=true restart=true replicated=true", + "deploy:setup": "harper deploy setup=true" }, "dependencies": { "@harperfast/schema-codegen": "^1.0.10", diff --git a/template-react/README.md b/template-react/README.md index f31ffcd..893ffe2 100644 --- a/template-react/README.md +++ b/template-react/README.md @@ -103,20 +103,53 @@ Take a look at the [default configuration](./config.yaml), which specifies how f ## Deployment -When you are ready, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in to your account, and create a cluster. +Deploy your app to a Harper cluster **by reference**: rather than uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit. -Come back and log in your local CLI to your cluster: +First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in, and create a cluster. Then log your local CLI in to it: ```sh harper login ``` -Then you can deploy your app to your cluster: +### One-time setup + +So the cluster can clone your (private) repository, register a read-only SSH **deploy key**: + +```sh +npm run deploy:setup +``` + +This generates the key, registers it with your cluster, and prints a public key to add to your repository under **Settings → Deploy keys**. A deploy key is scoped to this one repository and keeps working even if the person who created it leaves. (It uses Harper's `add_ssh_key`, available on Harper Pro / Fabric.) + +### Deploy ```sh npm run deploy ``` +This deploys the current commit — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again. + +### Deploy automatically from CI + +The included [GitHub Actions workflow](./.github/workflows/deploy.yaml) deploys whenever you push a version tag: + +```sh +git tag v1.0.0 +git push --tags +``` + +Add these repository secrets first, under **Settings → Secrets and variables → Actions**: + +- `CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`) +- `HARPER_CLI_USERNAME` and `HARPER_CLI_PASSWORD` — a cluster user allowed to deploy + +### Other options + +- **Public repository?** Skip the deploy key and let Harper clone over HTTPS (`git+https://…#`) with no cluster-side credentials. +- **Prefer to build in CI** instead of on your Harper nodes? Publish your app to a registry such as GitHub Packages and deploy it by version using `registryAuth`. + +See the [Harper deployment docs](https://docs.harperdb.io/reference/v5/components/applications#deploy_component) for both. + ## Keep Going! For more information about getting started with Harper and building applications, see our [getting started guide](https://docs.harperdb.io/docs). diff --git a/template-react/_github/workflow/deploy.yaml b/template-react/_github/workflow/deploy.yaml deleted file mode 100644 index cc5039e..0000000 --- a/template-react/_github/workflow/deploy.yaml +++ /dev/null @@ -1,33 +0,0 @@ -name: Deploy to Harper Fabric -on: - workflow_dispatch: -# push: -# branches: -# - main - -concurrency: - group: main - cancel-in-progress: false - -jobs: - deploy: - runs-on: ubuntu-latest - steps: - - name: Checkout code - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1 - with: - fetch-depth: 0 - fetch-tags: true - - name: Set up Node.js - uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0 - with: - cache: 'npm' - node-version-file: '.nvmrc' - - name: Install dependencies - run: npm ci - - name: Run unit tests - run: npm test - - name: Run lint - run: npm run lint - - name: Build & deploy - run: npm run deploy diff --git a/template-react/_github/workflows/deploy.yaml b/template-react/_github/workflows/deploy.yaml new file mode 100644 index 0000000..5b7ef1a --- /dev/null +++ b/template-react/_github/workflows/deploy.yaml @@ -0,0 +1,53 @@ +# Deploys this app to your Harper cluster by *reference* via `harper deploy by_ref=true` +# (`npm run deploy`). +# +# Runs on a version tag (e.g. `git tag v1.2.3 && git push --tags`) or manually. The Harper cluster +# fetches the tagged commit over SSH (pinned by its exact SHA, so peers can't diverge on a moved tag) +# using the read-only deploy key you registered once with `npm run deploy:setup`. +# +# Required repository secrets (Settings → Secrets and variables → Actions): +# CLI_TARGET your cluster's operations URL, e.g. https://my-cluster.harperdb.io:9925 +# HARPER_CLI_USERNAME a cluster user allowed to deploy +# HARPER_CLI_PASSWORD that user's password +# +# Public repo and want zero cluster-side auth, or prefer building in CI and publishing to a registry? +# See the "Deployment" section of the README for those alternatives. +name: Deploy to Harper Fabric +on: + workflow_dispatch: + push: + tags: + - 'v*' + +concurrency: + group: deploy + cancel-in-progress: false + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1 + with: + fetch-depth: 0 + fetch-tags: true + - name: Set up Node.js + uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0 + with: + cache: 'npm' + node-version-file: '.nvmrc' + - name: Install dependencies + run: npm ci + - name: Run unit tests + run: npm test + - name: Run lint + run: npm run lint + - name: Install Harper CLI + run: npm install -g harper + - name: Deploy + run: npm run deploy + env: + CLI_TARGET: ${{ secrets.CLI_TARGET }} + HARPER_CLI_USERNAME: ${{ secrets.HARPER_CLI_USERNAME }} + HARPER_CLI_PASSWORD: ${{ secrets.HARPER_CLI_PASSWORD }} diff --git a/template-react/package.json b/template-react/package.json index a6314da..6ded932 100644 --- a/template-react/package.json +++ b/template-react/package.json @@ -13,7 +13,8 @@ "test": "node --test test/*.test.js", "test:watch": "node --watch --test test/*.test.js", "build": "vite build", - "deploy": "harper deploy_component . restart=true replicated=true" + "deploy": "harper deploy by_ref=true restart=true replicated=true", + "deploy:setup": "harper deploy setup=true" }, "dependencies": { "@harperfast/schema-codegen": "^1.0.10", diff --git a/template-vanilla-ts/README.md b/template-vanilla-ts/README.md index 7ff7891..6556313 100644 --- a/template-vanilla-ts/README.md +++ b/template-vanilla-ts/README.md @@ -111,20 +111,53 @@ Take a look at the [default configuration](./config.yaml), which specifies how f ## Deployment -When you are ready, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in to your account, and create a cluster. +Deploy your app to a Harper cluster **by reference**: rather than uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit. -Come back and log in your local CLI to your cluster: +First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in, and create a cluster. Then log your local CLI in to it: ```sh harper login ``` -Then you can deploy your app to your cluster: +### One-time setup + +So the cluster can clone your (private) repository, register a read-only SSH **deploy key**: + +```sh +npm run deploy:setup +``` + +This generates the key, registers it with your cluster, and prints a public key to add to your repository under **Settings → Deploy keys**. A deploy key is scoped to this one repository and keeps working even if the person who created it leaves. (It uses Harper's `add_ssh_key`, available on Harper Pro / Fabric.) + +### Deploy ```sh npm run deploy ``` +This deploys the current commit — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again. + +### Deploy automatically from CI + +The included [GitHub Actions workflow](./.github/workflows/deploy.yaml) deploys whenever you push a version tag: + +```sh +git tag v1.0.0 +git push --tags +``` + +Add these repository secrets first, under **Settings → Secrets and variables → Actions**: + +- `CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`) +- `HARPER_CLI_USERNAME` and `HARPER_CLI_PASSWORD` — a cluster user allowed to deploy + +### Other options + +- **Public repository?** Skip the deploy key and let Harper clone over HTTPS (`git+https://…#`) with no cluster-side credentials. +- **Prefer to build in CI** instead of on your Harper nodes? Publish your app to a registry such as GitHub Packages and deploy it by version using `registryAuth`. + +See the [Harper deployment docs](https://docs.harperdb.io/reference/v5/components/applications#deploy_component) for both. + ## Keep Going! For more information about getting started with Harper and building applications, see our [getting started guide](https://docs.harperdb.io/docs). diff --git a/template-vanilla-ts/_github/workflow/deploy.yaml b/template-vanilla-ts/_github/workflow/deploy.yaml deleted file mode 100644 index e3ee65c..0000000 --- a/template-vanilla-ts/_github/workflow/deploy.yaml +++ /dev/null @@ -1,33 +0,0 @@ -name: Deploy to Harper Fabric -on: - workflow_dispatch: -# push: -# branches: -# - main - -concurrency: - group: main - cancel-in-progress: false - -jobs: - deploy: - runs-on: ubuntu-latest - steps: - - name: Checkout code - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1 - with: - fetch-depth: 0 - fetch-tags: true - - name: Set up Node.js - uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0 - with: - cache: 'npm' - node-version-file: '.nvmrc' - - name: Install dependencies - run: npm ci - - name: Run unit tests - run: npm test - - name: Run lint - run: npm run lint - - name: Deploy - run: npm run deploy diff --git a/template-vanilla-ts/_github/workflows/deploy.yaml b/template-vanilla-ts/_github/workflows/deploy.yaml new file mode 100644 index 0000000..5b7ef1a --- /dev/null +++ b/template-vanilla-ts/_github/workflows/deploy.yaml @@ -0,0 +1,53 @@ +# Deploys this app to your Harper cluster by *reference* via `harper deploy by_ref=true` +# (`npm run deploy`). +# +# Runs on a version tag (e.g. `git tag v1.2.3 && git push --tags`) or manually. The Harper cluster +# fetches the tagged commit over SSH (pinned by its exact SHA, so peers can't diverge on a moved tag) +# using the read-only deploy key you registered once with `npm run deploy:setup`. +# +# Required repository secrets (Settings → Secrets and variables → Actions): +# CLI_TARGET your cluster's operations URL, e.g. https://my-cluster.harperdb.io:9925 +# HARPER_CLI_USERNAME a cluster user allowed to deploy +# HARPER_CLI_PASSWORD that user's password +# +# Public repo and want zero cluster-side auth, or prefer building in CI and publishing to a registry? +# See the "Deployment" section of the README for those alternatives. +name: Deploy to Harper Fabric +on: + workflow_dispatch: + push: + tags: + - 'v*' + +concurrency: + group: deploy + cancel-in-progress: false + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1 + with: + fetch-depth: 0 + fetch-tags: true + - name: Set up Node.js + uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0 + with: + cache: 'npm' + node-version-file: '.nvmrc' + - name: Install dependencies + run: npm ci + - name: Run unit tests + run: npm test + - name: Run lint + run: npm run lint + - name: Install Harper CLI + run: npm install -g harper + - name: Deploy + run: npm run deploy + env: + CLI_TARGET: ${{ secrets.CLI_TARGET }} + HARPER_CLI_USERNAME: ${{ secrets.HARPER_CLI_USERNAME }} + HARPER_CLI_PASSWORD: ${{ secrets.HARPER_CLI_PASSWORD }} diff --git a/template-vanilla-ts/package.json b/template-vanilla-ts/package.json index 2677a3e..13f6eff 100644 --- a/template-vanilla-ts/package.json +++ b/template-vanilla-ts/package.json @@ -12,7 +12,8 @@ "format": "prettier --write .", "test": "node --test test/*.test.js", "test:watch": "node --watch --test test/*.test.js", - "deploy": "harper deploy_component . restart=true replicated=true" + "deploy": "harper deploy by_ref=true restart=true replicated=true", + "deploy:setup": "harper deploy setup=true" }, "devDependencies": { "@eslint/js": "^10.0.1", diff --git a/template-vanilla/README.md b/template-vanilla/README.md index 3e6ec4f..d8a32ee 100644 --- a/template-vanilla/README.md +++ b/template-vanilla/README.md @@ -103,20 +103,53 @@ Take a look at the [default configuration](./config.yaml), which specifies how f ## Deployment -When you are ready, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in to your account, and create a cluster. +Deploy your app to a Harper cluster **by reference**: rather than uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit. -Come back and log in your local CLI to your cluster: +First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in, and create a cluster. Then log your local CLI in to it: ```sh harper login ``` -Then you can deploy your app to your cluster: +### One-time setup + +So the cluster can clone your (private) repository, register a read-only SSH **deploy key**: + +```sh +npm run deploy:setup +``` + +This generates the key, registers it with your cluster, and prints a public key to add to your repository under **Settings → Deploy keys**. A deploy key is scoped to this one repository and keeps working even if the person who created it leaves. (It uses Harper's `add_ssh_key`, available on Harper Pro / Fabric.) + +### Deploy ```sh npm run deploy ``` +This deploys the current commit — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again. + +### Deploy automatically from CI + +The included [GitHub Actions workflow](./.github/workflows/deploy.yaml) deploys whenever you push a version tag: + +```sh +git tag v1.0.0 +git push --tags +``` + +Add these repository secrets first, under **Settings → Secrets and variables → Actions**: + +- `CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`) +- `HARPER_CLI_USERNAME` and `HARPER_CLI_PASSWORD` — a cluster user allowed to deploy + +### Other options + +- **Public repository?** Skip the deploy key and let Harper clone over HTTPS (`git+https://…#`) with no cluster-side credentials. +- **Prefer to build in CI** instead of on your Harper nodes? Publish your app to a registry such as GitHub Packages and deploy it by version using `registryAuth`. + +See the [Harper deployment docs](https://docs.harperdb.io/reference/v5/components/applications#deploy_component) for both. + ## Keep Going! For more information about getting started with Harper and building applications, see our [getting started guide](https://docs.harperdb.io/docs). diff --git a/template-vanilla/_github/workflow/deploy.yaml b/template-vanilla/_github/workflow/deploy.yaml deleted file mode 100644 index e3ee65c..0000000 --- a/template-vanilla/_github/workflow/deploy.yaml +++ /dev/null @@ -1,33 +0,0 @@ -name: Deploy to Harper Fabric -on: - workflow_dispatch: -# push: -# branches: -# - main - -concurrency: - group: main - cancel-in-progress: false - -jobs: - deploy: - runs-on: ubuntu-latest - steps: - - name: Checkout code - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1 - with: - fetch-depth: 0 - fetch-tags: true - - name: Set up Node.js - uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0 - with: - cache: 'npm' - node-version-file: '.nvmrc' - - name: Install dependencies - run: npm ci - - name: Run unit tests - run: npm test - - name: Run lint - run: npm run lint - - name: Deploy - run: npm run deploy diff --git a/template-vanilla/_github/workflows/deploy.yaml b/template-vanilla/_github/workflows/deploy.yaml new file mode 100644 index 0000000..5b7ef1a --- /dev/null +++ b/template-vanilla/_github/workflows/deploy.yaml @@ -0,0 +1,53 @@ +# Deploys this app to your Harper cluster by *reference* via `harper deploy by_ref=true` +# (`npm run deploy`). +# +# Runs on a version tag (e.g. `git tag v1.2.3 && git push --tags`) or manually. The Harper cluster +# fetches the tagged commit over SSH (pinned by its exact SHA, so peers can't diverge on a moved tag) +# using the read-only deploy key you registered once with `npm run deploy:setup`. +# +# Required repository secrets (Settings → Secrets and variables → Actions): +# CLI_TARGET your cluster's operations URL, e.g. https://my-cluster.harperdb.io:9925 +# HARPER_CLI_USERNAME a cluster user allowed to deploy +# HARPER_CLI_PASSWORD that user's password +# +# Public repo and want zero cluster-side auth, or prefer building in CI and publishing to a registry? +# See the "Deployment" section of the README for those alternatives. +name: Deploy to Harper Fabric +on: + workflow_dispatch: + push: + tags: + - 'v*' + +concurrency: + group: deploy + cancel-in-progress: false + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1 + with: + fetch-depth: 0 + fetch-tags: true + - name: Set up Node.js + uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0 + with: + cache: 'npm' + node-version-file: '.nvmrc' + - name: Install dependencies + run: npm ci + - name: Run unit tests + run: npm test + - name: Run lint + run: npm run lint + - name: Install Harper CLI + run: npm install -g harper + - name: Deploy + run: npm run deploy + env: + CLI_TARGET: ${{ secrets.CLI_TARGET }} + HARPER_CLI_USERNAME: ${{ secrets.HARPER_CLI_USERNAME }} + HARPER_CLI_PASSWORD: ${{ secrets.HARPER_CLI_PASSWORD }} diff --git a/template-vanilla/package.json b/template-vanilla/package.json index 2677a3e..13f6eff 100644 --- a/template-vanilla/package.json +++ b/template-vanilla/package.json @@ -12,7 +12,8 @@ "format": "prettier --write .", "test": "node --test test/*.test.js", "test:watch": "node --watch --test test/*.test.js", - "deploy": "harper deploy_component . restart=true replicated=true" + "deploy": "harper deploy by_ref=true restart=true replicated=true", + "deploy:setup": "harper deploy setup=true" }, "devDependencies": { "@eslint/js": "^10.0.1", diff --git a/template-vue-ssr/README.md b/template-vue-ssr/README.md index f31ffcd..893ffe2 100644 --- a/template-vue-ssr/README.md +++ b/template-vue-ssr/README.md @@ -103,20 +103,53 @@ Take a look at the [default configuration](./config.yaml), which specifies how f ## Deployment -When you are ready, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in to your account, and create a cluster. +Deploy your app to a Harper cluster **by reference**: rather than uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit. -Come back and log in your local CLI to your cluster: +First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in, and create a cluster. Then log your local CLI in to it: ```sh harper login ``` -Then you can deploy your app to your cluster: +### One-time setup + +So the cluster can clone your (private) repository, register a read-only SSH **deploy key**: + +```sh +npm run deploy:setup +``` + +This generates the key, registers it with your cluster, and prints a public key to add to your repository under **Settings → Deploy keys**. A deploy key is scoped to this one repository and keeps working even if the person who created it leaves. (It uses Harper's `add_ssh_key`, available on Harper Pro / Fabric.) + +### Deploy ```sh npm run deploy ``` +This deploys the current commit — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again. + +### Deploy automatically from CI + +The included [GitHub Actions workflow](./.github/workflows/deploy.yaml) deploys whenever you push a version tag: + +```sh +git tag v1.0.0 +git push --tags +``` + +Add these repository secrets first, under **Settings → Secrets and variables → Actions**: + +- `CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`) +- `HARPER_CLI_USERNAME` and `HARPER_CLI_PASSWORD` — a cluster user allowed to deploy + +### Other options + +- **Public repository?** Skip the deploy key and let Harper clone over HTTPS (`git+https://…#`) with no cluster-side credentials. +- **Prefer to build in CI** instead of on your Harper nodes? Publish your app to a registry such as GitHub Packages and deploy it by version using `registryAuth`. + +See the [Harper deployment docs](https://docs.harperdb.io/reference/v5/components/applications#deploy_component) for both. + ## Keep Going! For more information about getting started with Harper and building applications, see our [getting started guide](https://docs.harperdb.io/docs). diff --git a/template-vue-ssr/_github/workflow/deploy.yaml b/template-vue-ssr/_github/workflow/deploy.yaml deleted file mode 100644 index cc5039e..0000000 --- a/template-vue-ssr/_github/workflow/deploy.yaml +++ /dev/null @@ -1,33 +0,0 @@ -name: Deploy to Harper Fabric -on: - workflow_dispatch: -# push: -# branches: -# - main - -concurrency: - group: main - cancel-in-progress: false - -jobs: - deploy: - runs-on: ubuntu-latest - steps: - - name: Checkout code - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1 - with: - fetch-depth: 0 - fetch-tags: true - - name: Set up Node.js - uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0 - with: - cache: 'npm' - node-version-file: '.nvmrc' - - name: Install dependencies - run: npm ci - - name: Run unit tests - run: npm test - - name: Run lint - run: npm run lint - - name: Build & deploy - run: npm run deploy diff --git a/template-vue-ssr/_github/workflows/deploy.yaml b/template-vue-ssr/_github/workflows/deploy.yaml new file mode 100644 index 0000000..5b7ef1a --- /dev/null +++ b/template-vue-ssr/_github/workflows/deploy.yaml @@ -0,0 +1,53 @@ +# Deploys this app to your Harper cluster by *reference* via `harper deploy by_ref=true` +# (`npm run deploy`). +# +# Runs on a version tag (e.g. `git tag v1.2.3 && git push --tags`) or manually. The Harper cluster +# fetches the tagged commit over SSH (pinned by its exact SHA, so peers can't diverge on a moved tag) +# using the read-only deploy key you registered once with `npm run deploy:setup`. +# +# Required repository secrets (Settings → Secrets and variables → Actions): +# CLI_TARGET your cluster's operations URL, e.g. https://my-cluster.harperdb.io:9925 +# HARPER_CLI_USERNAME a cluster user allowed to deploy +# HARPER_CLI_PASSWORD that user's password +# +# Public repo and want zero cluster-side auth, or prefer building in CI and publishing to a registry? +# See the "Deployment" section of the README for those alternatives. +name: Deploy to Harper Fabric +on: + workflow_dispatch: + push: + tags: + - 'v*' + +concurrency: + group: deploy + cancel-in-progress: false + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1 + with: + fetch-depth: 0 + fetch-tags: true + - name: Set up Node.js + uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0 + with: + cache: 'npm' + node-version-file: '.nvmrc' + - name: Install dependencies + run: npm ci + - name: Run unit tests + run: npm test + - name: Run lint + run: npm run lint + - name: Install Harper CLI + run: npm install -g harper + - name: Deploy + run: npm run deploy + env: + CLI_TARGET: ${{ secrets.CLI_TARGET }} + HARPER_CLI_USERNAME: ${{ secrets.HARPER_CLI_USERNAME }} + HARPER_CLI_PASSWORD: ${{ secrets.HARPER_CLI_PASSWORD }} diff --git a/template-vue-ssr/package.json b/template-vue-ssr/package.json index c1d4808..8946f8f 100644 --- a/template-vue-ssr/package.json +++ b/template-vue-ssr/package.json @@ -13,7 +13,8 @@ "test": "node --test test/*.test.js", "test:watch": "node --watch --test test/*.test.js", "build": "vite build", - "deploy": "harper deploy_component . restart=true replicated=true" + "deploy": "harper deploy by_ref=true restart=true replicated=true", + "deploy:setup": "harper deploy setup=true" }, "dependencies": { "@harperfast/schema-codegen": "^1.0.10", diff --git a/template-vue-ts-ssr/README.md b/template-vue-ts-ssr/README.md index 90bc495..9af4e5f 100644 --- a/template-vue-ts-ssr/README.md +++ b/template-vue-ts-ssr/README.md @@ -111,20 +111,53 @@ Take a look at the [default configuration](./config.yaml), which specifies how f ## Deployment -When you are ready, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in to your account, and create a cluster. +Deploy your app to a Harper cluster **by reference**: rather than uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit. -Come back and log in your local CLI to your cluster: +First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in, and create a cluster. Then log your local CLI in to it: ```sh harper login ``` -Then you can deploy your app to your cluster: +### One-time setup + +So the cluster can clone your (private) repository, register a read-only SSH **deploy key**: + +```sh +npm run deploy:setup +``` + +This generates the key, registers it with your cluster, and prints a public key to add to your repository under **Settings → Deploy keys**. A deploy key is scoped to this one repository and keeps working even if the person who created it leaves. (It uses Harper's `add_ssh_key`, available on Harper Pro / Fabric.) + +### Deploy ```sh npm run deploy ``` +This deploys the current commit — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again. + +### Deploy automatically from CI + +The included [GitHub Actions workflow](./.github/workflows/deploy.yaml) deploys whenever you push a version tag: + +```sh +git tag v1.0.0 +git push --tags +``` + +Add these repository secrets first, under **Settings → Secrets and variables → Actions**: + +- `CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`) +- `HARPER_CLI_USERNAME` and `HARPER_CLI_PASSWORD` — a cluster user allowed to deploy + +### Other options + +- **Public repository?** Skip the deploy key and let Harper clone over HTTPS (`git+https://…#`) with no cluster-side credentials. +- **Prefer to build in CI** instead of on your Harper nodes? Publish your app to a registry such as GitHub Packages and deploy it by version using `registryAuth`. + +See the [Harper deployment docs](https://docs.harperdb.io/reference/v5/components/applications#deploy_component) for both. + ## Keep Going! For more information about getting started with Harper and building applications, see our [getting started guide](https://docs.harperdb.io/docs). diff --git a/template-vue-ts-ssr/_github/workflow/deploy.yaml b/template-vue-ts-ssr/_github/workflow/deploy.yaml deleted file mode 100644 index cc5039e..0000000 --- a/template-vue-ts-ssr/_github/workflow/deploy.yaml +++ /dev/null @@ -1,33 +0,0 @@ -name: Deploy to Harper Fabric -on: - workflow_dispatch: -# push: -# branches: -# - main - -concurrency: - group: main - cancel-in-progress: false - -jobs: - deploy: - runs-on: ubuntu-latest - steps: - - name: Checkout code - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1 - with: - fetch-depth: 0 - fetch-tags: true - - name: Set up Node.js - uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0 - with: - cache: 'npm' - node-version-file: '.nvmrc' - - name: Install dependencies - run: npm ci - - name: Run unit tests - run: npm test - - name: Run lint - run: npm run lint - - name: Build & deploy - run: npm run deploy diff --git a/template-vue-ts-ssr/_github/workflows/deploy.yaml b/template-vue-ts-ssr/_github/workflows/deploy.yaml new file mode 100644 index 0000000..5b7ef1a --- /dev/null +++ b/template-vue-ts-ssr/_github/workflows/deploy.yaml @@ -0,0 +1,53 @@ +# Deploys this app to your Harper cluster by *reference* via `harper deploy by_ref=true` +# (`npm run deploy`). +# +# Runs on a version tag (e.g. `git tag v1.2.3 && git push --tags`) or manually. The Harper cluster +# fetches the tagged commit over SSH (pinned by its exact SHA, so peers can't diverge on a moved tag) +# using the read-only deploy key you registered once with `npm run deploy:setup`. +# +# Required repository secrets (Settings → Secrets and variables → Actions): +# CLI_TARGET your cluster's operations URL, e.g. https://my-cluster.harperdb.io:9925 +# HARPER_CLI_USERNAME a cluster user allowed to deploy +# HARPER_CLI_PASSWORD that user's password +# +# Public repo and want zero cluster-side auth, or prefer building in CI and publishing to a registry? +# See the "Deployment" section of the README for those alternatives. +name: Deploy to Harper Fabric +on: + workflow_dispatch: + push: + tags: + - 'v*' + +concurrency: + group: deploy + cancel-in-progress: false + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1 + with: + fetch-depth: 0 + fetch-tags: true + - name: Set up Node.js + uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0 + with: + cache: 'npm' + node-version-file: '.nvmrc' + - name: Install dependencies + run: npm ci + - name: Run unit tests + run: npm test + - name: Run lint + run: npm run lint + - name: Install Harper CLI + run: npm install -g harper + - name: Deploy + run: npm run deploy + env: + CLI_TARGET: ${{ secrets.CLI_TARGET }} + HARPER_CLI_USERNAME: ${{ secrets.HARPER_CLI_USERNAME }} + HARPER_CLI_PASSWORD: ${{ secrets.HARPER_CLI_PASSWORD }} diff --git a/template-vue-ts-ssr/package.json b/template-vue-ts-ssr/package.json index 30e75f5..4cc9723 100644 --- a/template-vue-ts-ssr/package.json +++ b/template-vue-ts-ssr/package.json @@ -13,7 +13,8 @@ "test": "node --test test/*.test.ts", "test:watch": "node --watch --test test/*.test.ts", "build": "vite build", - "deploy": "harper deploy_component . restart=true replicated=true" + "deploy": "harper deploy by_ref=true restart=true replicated=true", + "deploy:setup": "harper deploy setup=true" }, "dependencies": { "@harperfast/schema-codegen": "^1.0.10", diff --git a/template-vue-ts/README.md b/template-vue-ts/README.md index 90bc495..9af4e5f 100644 --- a/template-vue-ts/README.md +++ b/template-vue-ts/README.md @@ -111,20 +111,53 @@ Take a look at the [default configuration](./config.yaml), which specifies how f ## Deployment -When you are ready, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in to your account, and create a cluster. +Deploy your app to a Harper cluster **by reference**: rather than uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit. -Come back and log in your local CLI to your cluster: +First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in, and create a cluster. Then log your local CLI in to it: ```sh harper login ``` -Then you can deploy your app to your cluster: +### One-time setup + +So the cluster can clone your (private) repository, register a read-only SSH **deploy key**: + +```sh +npm run deploy:setup +``` + +This generates the key, registers it with your cluster, and prints a public key to add to your repository under **Settings → Deploy keys**. A deploy key is scoped to this one repository and keeps working even if the person who created it leaves. (It uses Harper's `add_ssh_key`, available on Harper Pro / Fabric.) + +### Deploy ```sh npm run deploy ``` +This deploys the current commit — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again. + +### Deploy automatically from CI + +The included [GitHub Actions workflow](./.github/workflows/deploy.yaml) deploys whenever you push a version tag: + +```sh +git tag v1.0.0 +git push --tags +``` + +Add these repository secrets first, under **Settings → Secrets and variables → Actions**: + +- `CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`) +- `HARPER_CLI_USERNAME` and `HARPER_CLI_PASSWORD` — a cluster user allowed to deploy + +### Other options + +- **Public repository?** Skip the deploy key and let Harper clone over HTTPS (`git+https://…#`) with no cluster-side credentials. +- **Prefer to build in CI** instead of on your Harper nodes? Publish your app to a registry such as GitHub Packages and deploy it by version using `registryAuth`. + +See the [Harper deployment docs](https://docs.harperdb.io/reference/v5/components/applications#deploy_component) for both. + ## Keep Going! For more information about getting started with Harper and building applications, see our [getting started guide](https://docs.harperdb.io/docs). diff --git a/template-vue-ts/_github/workflow/deploy.yaml b/template-vue-ts/_github/workflow/deploy.yaml deleted file mode 100644 index cc5039e..0000000 --- a/template-vue-ts/_github/workflow/deploy.yaml +++ /dev/null @@ -1,33 +0,0 @@ -name: Deploy to Harper Fabric -on: - workflow_dispatch: -# push: -# branches: -# - main - -concurrency: - group: main - cancel-in-progress: false - -jobs: - deploy: - runs-on: ubuntu-latest - steps: - - name: Checkout code - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1 - with: - fetch-depth: 0 - fetch-tags: true - - name: Set up Node.js - uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0 - with: - cache: 'npm' - node-version-file: '.nvmrc' - - name: Install dependencies - run: npm ci - - name: Run unit tests - run: npm test - - name: Run lint - run: npm run lint - - name: Build & deploy - run: npm run deploy diff --git a/template-vue-ts/_github/workflows/deploy.yaml b/template-vue-ts/_github/workflows/deploy.yaml new file mode 100644 index 0000000..5b7ef1a --- /dev/null +++ b/template-vue-ts/_github/workflows/deploy.yaml @@ -0,0 +1,53 @@ +# Deploys this app to your Harper cluster by *reference* via `harper deploy by_ref=true` +# (`npm run deploy`). +# +# Runs on a version tag (e.g. `git tag v1.2.3 && git push --tags`) or manually. The Harper cluster +# fetches the tagged commit over SSH (pinned by its exact SHA, so peers can't diverge on a moved tag) +# using the read-only deploy key you registered once with `npm run deploy:setup`. +# +# Required repository secrets (Settings → Secrets and variables → Actions): +# CLI_TARGET your cluster's operations URL, e.g. https://my-cluster.harperdb.io:9925 +# HARPER_CLI_USERNAME a cluster user allowed to deploy +# HARPER_CLI_PASSWORD that user's password +# +# Public repo and want zero cluster-side auth, or prefer building in CI and publishing to a registry? +# See the "Deployment" section of the README for those alternatives. +name: Deploy to Harper Fabric +on: + workflow_dispatch: + push: + tags: + - 'v*' + +concurrency: + group: deploy + cancel-in-progress: false + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1 + with: + fetch-depth: 0 + fetch-tags: true + - name: Set up Node.js + uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0 + with: + cache: 'npm' + node-version-file: '.nvmrc' + - name: Install dependencies + run: npm ci + - name: Run unit tests + run: npm test + - name: Run lint + run: npm run lint + - name: Install Harper CLI + run: npm install -g harper + - name: Deploy + run: npm run deploy + env: + CLI_TARGET: ${{ secrets.CLI_TARGET }} + HARPER_CLI_USERNAME: ${{ secrets.HARPER_CLI_USERNAME }} + HARPER_CLI_PASSWORD: ${{ secrets.HARPER_CLI_PASSWORD }} diff --git a/template-vue-ts/package.json b/template-vue-ts/package.json index 30e75f5..4cc9723 100644 --- a/template-vue-ts/package.json +++ b/template-vue-ts/package.json @@ -13,7 +13,8 @@ "test": "node --test test/*.test.ts", "test:watch": "node --watch --test test/*.test.ts", "build": "vite build", - "deploy": "harper deploy_component . restart=true replicated=true" + "deploy": "harper deploy by_ref=true restart=true replicated=true", + "deploy:setup": "harper deploy setup=true" }, "dependencies": { "@harperfast/schema-codegen": "^1.0.10", diff --git a/template-vue/README.md b/template-vue/README.md index f31ffcd..893ffe2 100644 --- a/template-vue/README.md +++ b/template-vue/README.md @@ -103,20 +103,53 @@ Take a look at the [default configuration](./config.yaml), which specifies how f ## Deployment -When you are ready, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in to your account, and create a cluster. +Deploy your app to a Harper cluster **by reference**: rather than uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit. -Come back and log in your local CLI to your cluster: +First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in, and create a cluster. Then log your local CLI in to it: ```sh harper login ``` -Then you can deploy your app to your cluster: +### One-time setup + +So the cluster can clone your (private) repository, register a read-only SSH **deploy key**: + +```sh +npm run deploy:setup +``` + +This generates the key, registers it with your cluster, and prints a public key to add to your repository under **Settings → Deploy keys**. A deploy key is scoped to this one repository and keeps working even if the person who created it leaves. (It uses Harper's `add_ssh_key`, available on Harper Pro / Fabric.) + +### Deploy ```sh npm run deploy ``` +This deploys the current commit — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again. + +### Deploy automatically from CI + +The included [GitHub Actions workflow](./.github/workflows/deploy.yaml) deploys whenever you push a version tag: + +```sh +git tag v1.0.0 +git push --tags +``` + +Add these repository secrets first, under **Settings → Secrets and variables → Actions**: + +- `CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`) +- `HARPER_CLI_USERNAME` and `HARPER_CLI_PASSWORD` — a cluster user allowed to deploy + +### Other options + +- **Public repository?** Skip the deploy key and let Harper clone over HTTPS (`git+https://…#`) with no cluster-side credentials. +- **Prefer to build in CI** instead of on your Harper nodes? Publish your app to a registry such as GitHub Packages and deploy it by version using `registryAuth`. + +See the [Harper deployment docs](https://docs.harperdb.io/reference/v5/components/applications#deploy_component) for both. + ## Keep Going! For more information about getting started with Harper and building applications, see our [getting started guide](https://docs.harperdb.io/docs). diff --git a/template-vue/_github/workflow/deploy.yaml b/template-vue/_github/workflow/deploy.yaml deleted file mode 100644 index cc5039e..0000000 --- a/template-vue/_github/workflow/deploy.yaml +++ /dev/null @@ -1,33 +0,0 @@ -name: Deploy to Harper Fabric -on: - workflow_dispatch: -# push: -# branches: -# - main - -concurrency: - group: main - cancel-in-progress: false - -jobs: - deploy: - runs-on: ubuntu-latest - steps: - - name: Checkout code - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1 - with: - fetch-depth: 0 - fetch-tags: true - - name: Set up Node.js - uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0 - with: - cache: 'npm' - node-version-file: '.nvmrc' - - name: Install dependencies - run: npm ci - - name: Run unit tests - run: npm test - - name: Run lint - run: npm run lint - - name: Build & deploy - run: npm run deploy diff --git a/template-vue/_github/workflows/deploy.yaml b/template-vue/_github/workflows/deploy.yaml new file mode 100644 index 0000000..5b7ef1a --- /dev/null +++ b/template-vue/_github/workflows/deploy.yaml @@ -0,0 +1,53 @@ +# Deploys this app to your Harper cluster by *reference* via `harper deploy by_ref=true` +# (`npm run deploy`). +# +# Runs on a version tag (e.g. `git tag v1.2.3 && git push --tags`) or manually. The Harper cluster +# fetches the tagged commit over SSH (pinned by its exact SHA, so peers can't diverge on a moved tag) +# using the read-only deploy key you registered once with `npm run deploy:setup`. +# +# Required repository secrets (Settings → Secrets and variables → Actions): +# CLI_TARGET your cluster's operations URL, e.g. https://my-cluster.harperdb.io:9925 +# HARPER_CLI_USERNAME a cluster user allowed to deploy +# HARPER_CLI_PASSWORD that user's password +# +# Public repo and want zero cluster-side auth, or prefer building in CI and publishing to a registry? +# See the "Deployment" section of the README for those alternatives. +name: Deploy to Harper Fabric +on: + workflow_dispatch: + push: + tags: + - 'v*' + +concurrency: + group: deploy + cancel-in-progress: false + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1 + with: + fetch-depth: 0 + fetch-tags: true + - name: Set up Node.js + uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0 + with: + cache: 'npm' + node-version-file: '.nvmrc' + - name: Install dependencies + run: npm ci + - name: Run unit tests + run: npm test + - name: Run lint + run: npm run lint + - name: Install Harper CLI + run: npm install -g harper + - name: Deploy + run: npm run deploy + env: + CLI_TARGET: ${{ secrets.CLI_TARGET }} + HARPER_CLI_USERNAME: ${{ secrets.HARPER_CLI_USERNAME }} + HARPER_CLI_PASSWORD: ${{ secrets.HARPER_CLI_PASSWORD }} diff --git a/template-vue/package.json b/template-vue/package.json index c1d4808..8946f8f 100644 --- a/template-vue/package.json +++ b/template-vue/package.json @@ -13,7 +13,8 @@ "test": "node --test test/*.test.js", "test:watch": "node --watch --test test/*.test.js", "build": "vite build", - "deploy": "harper deploy_component . restart=true replicated=true" + "deploy": "harper deploy by_ref=true restart=true replicated=true", + "deploy:setup": "harper deploy setup=true" }, "dependencies": { "@harperfast/schema-codegen": "^1.0.10", diff --git a/template.tests/template.test.js b/template.tests/template.test.js index 0bc2504..b6582d9 100644 --- a/template.tests/template.test.js +++ b/template.tests/template.test.js @@ -69,15 +69,25 @@ describe('Integration tests', () => { const templateDir = path.resolve(root, `template-${template}`); if (fs.existsSync(path.join(templateDir, '_env'))) { expect(fs.existsSync(path.join(targetDir, '.env'))).toBe(true); + // Credentials come from `harper login` (local) or GitHub Actions secrets (CI); the + // scaffolded .env only selects the target cluster. const envContent = fs.readFileSync(path.join(targetDir, '.env'), 'utf-8'); - expect(envContent).toContain('CLI_TARGET_USERNAME'); - expect(envContent).toContain('CLI_TARGET_PASSWORD'); expect(envContent).toContain('CLI_TARGET'); + expect(envContent).not.toContain('CLI_TARGET_USERNAME'); + expect(envContent).not.toContain('CLI_TARGET_PASSWORD'); } if (fs.existsSync(path.join(templateDir, '_env.example'))) { expect(fs.existsSync(path.join(targetDir, '.env.example'))).toBe(true); } + + // Deploy-by-reference scaffolding: the workflow must live under `.github/workflows/` + // (plural — GitHub only runs workflows there), and deploy is driven by the native harper CLI + // (no per-project scripts). + expect(fs.existsSync(path.join(targetDir, '.github', 'workflows', 'deploy.yaml'))).toBe(true); + expect(fs.existsSync(path.join(targetDir, 'scripts', 'deploy.mjs'))).toBe(false); + expect(pkgJson.scripts.deploy).toBe('harper deploy by_ref=true restart=true replicated=true'); + expect(pkgJson.scripts['deploy:setup']).toBe('harper deploy setup=true'); }); } }); diff --git a/templates-shared/all/_github/workflows/deploy.yaml b/templates-shared/all/_github/workflows/deploy.yaml new file mode 100644 index 0000000..5b7ef1a --- /dev/null +++ b/templates-shared/all/_github/workflows/deploy.yaml @@ -0,0 +1,53 @@ +# Deploys this app to your Harper cluster by *reference* via `harper deploy by_ref=true` +# (`npm run deploy`). +# +# Runs on a version tag (e.g. `git tag v1.2.3 && git push --tags`) or manually. The Harper cluster +# fetches the tagged commit over SSH (pinned by its exact SHA, so peers can't diverge on a moved tag) +# using the read-only deploy key you registered once with `npm run deploy:setup`. +# +# Required repository secrets (Settings → Secrets and variables → Actions): +# CLI_TARGET your cluster's operations URL, e.g. https://my-cluster.harperdb.io:9925 +# HARPER_CLI_USERNAME a cluster user allowed to deploy +# HARPER_CLI_PASSWORD that user's password +# +# Public repo and want zero cluster-side auth, or prefer building in CI and publishing to a registry? +# See the "Deployment" section of the README for those alternatives. +name: Deploy to Harper Fabric +on: + workflow_dispatch: + push: + tags: + - 'v*' + +concurrency: + group: deploy + cancel-in-progress: false + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1 + with: + fetch-depth: 0 + fetch-tags: true + - name: Set up Node.js + uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0 + with: + cache: 'npm' + node-version-file: '.nvmrc' + - name: Install dependencies + run: npm ci + - name: Run unit tests + run: npm test + - name: Run lint + run: npm run lint + - name: Install Harper CLI + run: npm install -g harper + - name: Deploy + run: npm run deploy + env: + CLI_TARGET: ${{ secrets.CLI_TARGET }} + HARPER_CLI_USERNAME: ${{ secrets.HARPER_CLI_USERNAME }} + HARPER_CLI_PASSWORD: ${{ secrets.HARPER_CLI_PASSWORD }} From a15baa988abefedc3809d3803be95a39400d023b Mon Sep 17 00:00:00 2001 From: Dawson Toth Date: Fri, 17 Jul 2026 14:24:19 -0400 Subject: [PATCH 2/3] =?UTF-8?q?fix(templates):=20address=20PR=20review=20?= =?UTF-8?q?=E2=80=94=20pin=20harper=20CLI,=20exclude=20legacy=20early-hint?= =?UTF-8?q?s?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Pin the workflow's global install to `harper@^5.2.0` (the 5.2 line where deploy-by-reference lands; blocks a breaking 6.x bump) instead of unpinned latest. Exclude template-early-hints (a legacy harperdb EdgeWorker example, not published via npm create harper) from the deploy migration: remove the stray _github workflow it got via fan-out, and filter _github out of applySharedTemplates for it so it isn't re-added (it keeps every other shared file). The per-template deploy.yaml duplication is intentional (templates-shared/README.md: shared files are committed into each template for discoverability + wholesale-copy scaffolding), so it's left as-is. Co-Authored-By: Claude Opus 4.8 --- .../_github/workflows/deploy.yaml | 53 ------------------- .../_github/workflows/deploy.yaml | 3 +- .../_github/workflows/deploy.yaml | 3 +- .../_github/workflows/deploy.yaml | 3 +- template-react/_github/workflows/deploy.yaml | 3 +- .../_github/workflows/deploy.yaml | 3 +- .../_github/workflows/deploy.yaml | 3 +- .../_github/workflows/deploy.yaml | 3 +- .../_github/workflows/deploy.yaml | 3 +- template-vue-ts/_github/workflows/deploy.yaml | 3 +- template-vue/_github/workflows/deploy.yaml | 3 +- .../all/_github/workflows/deploy.yaml | 3 +- templates-shared/applySharedTemplates.js | 9 +++- 13 files changed, 30 insertions(+), 65 deletions(-) delete mode 100644 template-early-hints/_github/workflows/deploy.yaml diff --git a/template-early-hints/_github/workflows/deploy.yaml b/template-early-hints/_github/workflows/deploy.yaml deleted file mode 100644 index 5b7ef1a..0000000 --- a/template-early-hints/_github/workflows/deploy.yaml +++ /dev/null @@ -1,53 +0,0 @@ -# Deploys this app to your Harper cluster by *reference* via `harper deploy by_ref=true` -# (`npm run deploy`). -# -# Runs on a version tag (e.g. `git tag v1.2.3 && git push --tags`) or manually. The Harper cluster -# fetches the tagged commit over SSH (pinned by its exact SHA, so peers can't diverge on a moved tag) -# using the read-only deploy key you registered once with `npm run deploy:setup`. -# -# Required repository secrets (Settings → Secrets and variables → Actions): -# CLI_TARGET your cluster's operations URL, e.g. https://my-cluster.harperdb.io:9925 -# HARPER_CLI_USERNAME a cluster user allowed to deploy -# HARPER_CLI_PASSWORD that user's password -# -# Public repo and want zero cluster-side auth, or prefer building in CI and publishing to a registry? -# See the "Deployment" section of the README for those alternatives. -name: Deploy to Harper Fabric -on: - workflow_dispatch: - push: - tags: - - 'v*' - -concurrency: - group: deploy - cancel-in-progress: false - -jobs: - deploy: - runs-on: ubuntu-latest - steps: - - name: Checkout code - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1 - with: - fetch-depth: 0 - fetch-tags: true - - name: Set up Node.js - uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0 - with: - cache: 'npm' - node-version-file: '.nvmrc' - - name: Install dependencies - run: npm ci - - name: Run unit tests - run: npm test - - name: Run lint - run: npm run lint - - name: Install Harper CLI - run: npm install -g harper - - name: Deploy - run: npm run deploy - env: - CLI_TARGET: ${{ secrets.CLI_TARGET }} - HARPER_CLI_USERNAME: ${{ secrets.HARPER_CLI_USERNAME }} - HARPER_CLI_PASSWORD: ${{ secrets.HARPER_CLI_PASSWORD }} diff --git a/template-react-ssr/_github/workflows/deploy.yaml b/template-react-ssr/_github/workflows/deploy.yaml index 5b7ef1a..c73ffd9 100644 --- a/template-react-ssr/_github/workflows/deploy.yaml +++ b/template-react-ssr/_github/workflows/deploy.yaml @@ -44,7 +44,8 @@ jobs: - name: Run lint run: npm run lint - name: Install Harper CLI - run: npm install -g harper + # Pinned to the 5.2 line (where deploy-by-reference lands); ^5.2.0 blocks a breaking 6.x bump. + run: npm install -g harper@^5.2.0 - name: Deploy run: npm run deploy env: diff --git a/template-react-ts-ssr/_github/workflows/deploy.yaml b/template-react-ts-ssr/_github/workflows/deploy.yaml index 5b7ef1a..c73ffd9 100644 --- a/template-react-ts-ssr/_github/workflows/deploy.yaml +++ b/template-react-ts-ssr/_github/workflows/deploy.yaml @@ -44,7 +44,8 @@ jobs: - name: Run lint run: npm run lint - name: Install Harper CLI - run: npm install -g harper + # Pinned to the 5.2 line (where deploy-by-reference lands); ^5.2.0 blocks a breaking 6.x bump. + run: npm install -g harper@^5.2.0 - name: Deploy run: npm run deploy env: diff --git a/template-react-ts/_github/workflows/deploy.yaml b/template-react-ts/_github/workflows/deploy.yaml index 5b7ef1a..c73ffd9 100644 --- a/template-react-ts/_github/workflows/deploy.yaml +++ b/template-react-ts/_github/workflows/deploy.yaml @@ -44,7 +44,8 @@ jobs: - name: Run lint run: npm run lint - name: Install Harper CLI - run: npm install -g harper + # Pinned to the 5.2 line (where deploy-by-reference lands); ^5.2.0 blocks a breaking 6.x bump. + run: npm install -g harper@^5.2.0 - name: Deploy run: npm run deploy env: diff --git a/template-react/_github/workflows/deploy.yaml b/template-react/_github/workflows/deploy.yaml index 5b7ef1a..c73ffd9 100644 --- a/template-react/_github/workflows/deploy.yaml +++ b/template-react/_github/workflows/deploy.yaml @@ -44,7 +44,8 @@ jobs: - name: Run lint run: npm run lint - name: Install Harper CLI - run: npm install -g harper + # Pinned to the 5.2 line (where deploy-by-reference lands); ^5.2.0 blocks a breaking 6.x bump. + run: npm install -g harper@^5.2.0 - name: Deploy run: npm run deploy env: diff --git a/template-vanilla-ts/_github/workflows/deploy.yaml b/template-vanilla-ts/_github/workflows/deploy.yaml index 5b7ef1a..c73ffd9 100644 --- a/template-vanilla-ts/_github/workflows/deploy.yaml +++ b/template-vanilla-ts/_github/workflows/deploy.yaml @@ -44,7 +44,8 @@ jobs: - name: Run lint run: npm run lint - name: Install Harper CLI - run: npm install -g harper + # Pinned to the 5.2 line (where deploy-by-reference lands); ^5.2.0 blocks a breaking 6.x bump. + run: npm install -g harper@^5.2.0 - name: Deploy run: npm run deploy env: diff --git a/template-vanilla/_github/workflows/deploy.yaml b/template-vanilla/_github/workflows/deploy.yaml index 5b7ef1a..c73ffd9 100644 --- a/template-vanilla/_github/workflows/deploy.yaml +++ b/template-vanilla/_github/workflows/deploy.yaml @@ -44,7 +44,8 @@ jobs: - name: Run lint run: npm run lint - name: Install Harper CLI - run: npm install -g harper + # Pinned to the 5.2 line (where deploy-by-reference lands); ^5.2.0 blocks a breaking 6.x bump. + run: npm install -g harper@^5.2.0 - name: Deploy run: npm run deploy env: diff --git a/template-vue-ssr/_github/workflows/deploy.yaml b/template-vue-ssr/_github/workflows/deploy.yaml index 5b7ef1a..c73ffd9 100644 --- a/template-vue-ssr/_github/workflows/deploy.yaml +++ b/template-vue-ssr/_github/workflows/deploy.yaml @@ -44,7 +44,8 @@ jobs: - name: Run lint run: npm run lint - name: Install Harper CLI - run: npm install -g harper + # Pinned to the 5.2 line (where deploy-by-reference lands); ^5.2.0 blocks a breaking 6.x bump. + run: npm install -g harper@^5.2.0 - name: Deploy run: npm run deploy env: diff --git a/template-vue-ts-ssr/_github/workflows/deploy.yaml b/template-vue-ts-ssr/_github/workflows/deploy.yaml index 5b7ef1a..c73ffd9 100644 --- a/template-vue-ts-ssr/_github/workflows/deploy.yaml +++ b/template-vue-ts-ssr/_github/workflows/deploy.yaml @@ -44,7 +44,8 @@ jobs: - name: Run lint run: npm run lint - name: Install Harper CLI - run: npm install -g harper + # Pinned to the 5.2 line (where deploy-by-reference lands); ^5.2.0 blocks a breaking 6.x bump. + run: npm install -g harper@^5.2.0 - name: Deploy run: npm run deploy env: diff --git a/template-vue-ts/_github/workflows/deploy.yaml b/template-vue-ts/_github/workflows/deploy.yaml index 5b7ef1a..c73ffd9 100644 --- a/template-vue-ts/_github/workflows/deploy.yaml +++ b/template-vue-ts/_github/workflows/deploy.yaml @@ -44,7 +44,8 @@ jobs: - name: Run lint run: npm run lint - name: Install Harper CLI - run: npm install -g harper + # Pinned to the 5.2 line (where deploy-by-reference lands); ^5.2.0 blocks a breaking 6.x bump. + run: npm install -g harper@^5.2.0 - name: Deploy run: npm run deploy env: diff --git a/template-vue/_github/workflows/deploy.yaml b/template-vue/_github/workflows/deploy.yaml index 5b7ef1a..c73ffd9 100644 --- a/template-vue/_github/workflows/deploy.yaml +++ b/template-vue/_github/workflows/deploy.yaml @@ -44,7 +44,8 @@ jobs: - name: Run lint run: npm run lint - name: Install Harper CLI - run: npm install -g harper + # Pinned to the 5.2 line (where deploy-by-reference lands); ^5.2.0 blocks a breaking 6.x bump. + run: npm install -g harper@^5.2.0 - name: Deploy run: npm run deploy env: diff --git a/templates-shared/all/_github/workflows/deploy.yaml b/templates-shared/all/_github/workflows/deploy.yaml index 5b7ef1a..c73ffd9 100644 --- a/templates-shared/all/_github/workflows/deploy.yaml +++ b/templates-shared/all/_github/workflows/deploy.yaml @@ -44,7 +44,8 @@ jobs: - name: Run lint run: npm run lint - name: Install Harper CLI - run: npm install -g harper + # Pinned to the 5.2 line (where deploy-by-reference lands); ^5.2.0 blocks a breaking 6.x bump. + run: npm install -g harper@^5.2.0 - name: Deploy run: npm run deploy env: diff --git a/templates-shared/applySharedTemplates.js b/templates-shared/applySharedTemplates.js index 1e35766..7efb867 100644 --- a/templates-shared/applySharedTemplates.js +++ b/templates-shared/applySharedTemplates.js @@ -19,11 +19,18 @@ import { copyDir } from '../lib/fs/copyDir.js'; 'template-vue-ts-ssr', ], }; + // template-early-hints is a legacy `harperdb` EdgeWorker example (not published via + // `npm create harper`), so it is intentionally excluded from the deploy-by-reference + // migration — it must not receive the `_github` deploy workflow that targets the modern + // `harper` CLI. It still gets every other shared file. + const excludeGithubForEarlyHints = (src) => !src.split(path.sep).includes('_github'); + for (const key in copiesToMake) { const fromShared = path.resolve(import.meta.dirname, key); for (const targetTemplate of copiesToMake[key]) { const toTemplate = path.resolve(import.meta.dirname, '..', targetTemplate); - copyDir(fromShared, toTemplate); + const filter = targetTemplate === 'template-early-hints' ? excludeGithubForEarlyHints : undefined; + copyDir(fromShared, toTemplate, filter); } } })(); From 6199d28776a419c9f16347bfe19cb04a52ee0582 Mon Sep 17 00:00:00 2001 From: Dawson Toth Date: Fri, 17 Jul 2026 14:50:09 -0400 Subject: [PATCH 3/3] refactor(deploy): reconcile to sealed-token + git+https credential model Aligns the scaffold with where the deploy design landed (harper#1799 in-memory git-host credential + client-side-sealed durable tokens) instead of SSH deploy keys: deploy -> `harper deploy by_ref=true credential=github.com ...` (git+https ref + a sealed-token credential reference the cluster resolves at clone time; public repos drop credential=github.com). deploy:setup -> `harper deploy setup=true` seals a durable GitHub/npm token locally with the cluster's public key and stores only ciphertext. README rewritten around the sealed-token flow; the workflow no longer handles any token itself. Depends on harper#1777 (by_ref git+https + credential), harper#1778 (deploy setup), harper#1799. Co-Authored-By: Claude Opus 4.8 --- template-react-ssr/README.md | 19 ++++++++++--------- .../_github/workflows/deploy.yaml | 9 +++++---- template-react-ssr/package.json | 2 +- template-react-ts-ssr/README.md | 19 ++++++++++--------- .../_github/workflows/deploy.yaml | 9 +++++---- template-react-ts-ssr/package.json | 2 +- template-react-ts/README.md | 19 ++++++++++--------- .../_github/workflows/deploy.yaml | 9 +++++---- template-react-ts/package.json | 2 +- template-react/README.md | 19 ++++++++++--------- template-react/_github/workflows/deploy.yaml | 9 +++++---- template-react/package.json | 2 +- template-vanilla-ts/README.md | 19 ++++++++++--------- .../_github/workflows/deploy.yaml | 9 +++++---- template-vanilla-ts/package.json | 2 +- template-vanilla/README.md | 19 ++++++++++--------- .../_github/workflows/deploy.yaml | 9 +++++---- template-vanilla/package.json | 2 +- template-vue-ssr/README.md | 19 ++++++++++--------- .../_github/workflows/deploy.yaml | 9 +++++---- template-vue-ssr/package.json | 2 +- template-vue-ts-ssr/README.md | 19 ++++++++++--------- .../_github/workflows/deploy.yaml | 9 +++++---- template-vue-ts-ssr/package.json | 2 +- template-vue-ts/README.md | 19 ++++++++++--------- template-vue-ts/_github/workflows/deploy.yaml | 9 +++++---- template-vue-ts/package.json | 2 +- template-vue/README.md | 19 ++++++++++--------- template-vue/_github/workflows/deploy.yaml | 9 +++++---- template-vue/package.json | 2 +- template.tests/template.test.js | 4 +++- .../all/_github/workflows/deploy.yaml | 9 +++++---- 32 files changed, 168 insertions(+), 145 deletions(-) diff --git a/template-react-ssr/README.md b/template-react-ssr/README.md index 893ffe2..1da0137 100644 --- a/template-react-ssr/README.md +++ b/template-react-ssr/README.md @@ -103,7 +103,7 @@ Take a look at the [default configuration](./config.yaml), which specifies how f ## Deployment -Deploy your app to a Harper cluster **by reference**: rather than uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit. +Deploy your app to a Harper cluster **by reference**: instead of uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit. First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in, and create a cluster. Then log your local CLI in to it: @@ -111,15 +111,17 @@ First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log i harper login ``` -### One-time setup +### One-time setup (private repos) -So the cluster can clone your (private) repository, register a read-only SSH **deploy key**: +So the cluster can clone your private repository, give it a read-only token — sealed on your machine, stored encrypted: ```sh npm run deploy:setup ``` -This generates the key, registers it with your cluster, and prints a public key to add to your repository under **Settings → Deploy keys**. A deploy key is scoped to this one repository and keeps working even if the person who created it leaves. (It uses Harper's `add_ssh_key`, available on Harper Pro / Fabric.) +This fetches your cluster's public key, has you provide a GitHub token (a fine-grained PAT with **Contents: Read-only**, or your `gh` CLI session), **encrypts it locally**, and stores only the ciphertext in the cluster's secret store. The plaintext never leaves your machine; the cluster decrypts it in memory only while cloning. Because the token is durable, rollbacks keep working for as long as it's valid. + +> Public repo? Skip this step and drop `credential=github.com` from the `deploy` script — no credential is needed. ### Deploy @@ -127,7 +129,7 @@ This generates the key, registers it with your cluster, and prints a public key npm run deploy ``` -This deploys the current commit — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again. +This deploys the current commit over `git+https` — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again. ### Deploy automatically from CI @@ -143,12 +145,11 @@ Add these repository secrets first, under **Settings → Secrets and variables - `CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`) - `HARPER_CLI_USERNAME` and `HARPER_CLI_PASSWORD` — a cluster user allowed to deploy -### Other options +The clone credential already lives in the cluster from `npm run deploy:setup`, so CI never handles a token itself. -- **Public repository?** Skip the deploy key and let Harper clone over HTTPS (`git+https://…#`) with no cluster-side credentials. -- **Prefer to build in CI** instead of on your Harper nodes? Publish your app to a registry such as GitHub Packages and deploy it by version using `registryAuth`. +### Private npm dependencies -See the [Harper deployment docs](https://docs.harperdb.io/reference/v5/components/applications#deploy_component) for both. +If your app depends on private npm packages, run `npm run deploy:setup` again and choose the npm registry — the same sealed-token flow, stored as a separate credential. ## Keep Going! diff --git a/template-react-ssr/_github/workflows/deploy.yaml b/template-react-ssr/_github/workflows/deploy.yaml index c73ffd9..16e83aa 100644 --- a/template-react-ssr/_github/workflows/deploy.yaml +++ b/template-react-ssr/_github/workflows/deploy.yaml @@ -2,16 +2,17 @@ # (`npm run deploy`). # # Runs on a version tag (e.g. `git tag v1.2.3 && git push --tags`) or manually. The Harper cluster -# fetches the tagged commit over SSH (pinned by its exact SHA, so peers can't diverge on a moved tag) -# using the read-only deploy key you registered once with `npm run deploy:setup`. +# fetches the tagged commit over git+https (pinned by its exact SHA, so peers can't diverge on a +# moved tag), authenticating a private clone with the encrypted token you sealed once via +# `npm run deploy:setup`. The credential lives on the cluster, so this workflow handles no token. # # Required repository secrets (Settings → Secrets and variables → Actions): # CLI_TARGET your cluster's operations URL, e.g. https://my-cluster.harperdb.io:9925 # HARPER_CLI_USERNAME a cluster user allowed to deploy # HARPER_CLI_PASSWORD that user's password # -# Public repo and want zero cluster-side auth, or prefer building in CI and publishing to a registry? -# See the "Deployment" section of the README for those alternatives. +# Public repo? Drop `credential=github.com` from the `deploy` script — no cluster-side auth needed. +# See the "Deployment" section of the README for details. name: Deploy to Harper Fabric on: workflow_dispatch: diff --git a/template-react-ssr/package.json b/template-react-ssr/package.json index 6ded932..41fc54a 100644 --- a/template-react-ssr/package.json +++ b/template-react-ssr/package.json @@ -13,7 +13,7 @@ "test": "node --test test/*.test.js", "test:watch": "node --watch --test test/*.test.js", "build": "vite build", - "deploy": "harper deploy by_ref=true restart=true replicated=true", + "deploy": "harper deploy by_ref=true credential=github.com restart=true replicated=true", "deploy:setup": "harper deploy setup=true" }, "dependencies": { diff --git a/template-react-ts-ssr/README.md b/template-react-ts-ssr/README.md index 9af4e5f..eaeff6f 100644 --- a/template-react-ts-ssr/README.md +++ b/template-react-ts-ssr/README.md @@ -111,7 +111,7 @@ Take a look at the [default configuration](./config.yaml), which specifies how f ## Deployment -Deploy your app to a Harper cluster **by reference**: rather than uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit. +Deploy your app to a Harper cluster **by reference**: instead of uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit. First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in, and create a cluster. Then log your local CLI in to it: @@ -119,15 +119,17 @@ First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log i harper login ``` -### One-time setup +### One-time setup (private repos) -So the cluster can clone your (private) repository, register a read-only SSH **deploy key**: +So the cluster can clone your private repository, give it a read-only token — sealed on your machine, stored encrypted: ```sh npm run deploy:setup ``` -This generates the key, registers it with your cluster, and prints a public key to add to your repository under **Settings → Deploy keys**. A deploy key is scoped to this one repository and keeps working even if the person who created it leaves. (It uses Harper's `add_ssh_key`, available on Harper Pro / Fabric.) +This fetches your cluster's public key, has you provide a GitHub token (a fine-grained PAT with **Contents: Read-only**, or your `gh` CLI session), **encrypts it locally**, and stores only the ciphertext in the cluster's secret store. The plaintext never leaves your machine; the cluster decrypts it in memory only while cloning. Because the token is durable, rollbacks keep working for as long as it's valid. + +> Public repo? Skip this step and drop `credential=github.com` from the `deploy` script — no credential is needed. ### Deploy @@ -135,7 +137,7 @@ This generates the key, registers it with your cluster, and prints a public key npm run deploy ``` -This deploys the current commit — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again. +This deploys the current commit over `git+https` — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again. ### Deploy automatically from CI @@ -151,12 +153,11 @@ Add these repository secrets first, under **Settings → Secrets and variables - `CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`) - `HARPER_CLI_USERNAME` and `HARPER_CLI_PASSWORD` — a cluster user allowed to deploy -### Other options +The clone credential already lives in the cluster from `npm run deploy:setup`, so CI never handles a token itself. -- **Public repository?** Skip the deploy key and let Harper clone over HTTPS (`git+https://…#`) with no cluster-side credentials. -- **Prefer to build in CI** instead of on your Harper nodes? Publish your app to a registry such as GitHub Packages and deploy it by version using `registryAuth`. +### Private npm dependencies -See the [Harper deployment docs](https://docs.harperdb.io/reference/v5/components/applications#deploy_component) for both. +If your app depends on private npm packages, run `npm run deploy:setup` again and choose the npm registry — the same sealed-token flow, stored as a separate credential. ## Keep Going! diff --git a/template-react-ts-ssr/_github/workflows/deploy.yaml b/template-react-ts-ssr/_github/workflows/deploy.yaml index c73ffd9..16e83aa 100644 --- a/template-react-ts-ssr/_github/workflows/deploy.yaml +++ b/template-react-ts-ssr/_github/workflows/deploy.yaml @@ -2,16 +2,17 @@ # (`npm run deploy`). # # Runs on a version tag (e.g. `git tag v1.2.3 && git push --tags`) or manually. The Harper cluster -# fetches the tagged commit over SSH (pinned by its exact SHA, so peers can't diverge on a moved tag) -# using the read-only deploy key you registered once with `npm run deploy:setup`. +# fetches the tagged commit over git+https (pinned by its exact SHA, so peers can't diverge on a +# moved tag), authenticating a private clone with the encrypted token you sealed once via +# `npm run deploy:setup`. The credential lives on the cluster, so this workflow handles no token. # # Required repository secrets (Settings → Secrets and variables → Actions): # CLI_TARGET your cluster's operations URL, e.g. https://my-cluster.harperdb.io:9925 # HARPER_CLI_USERNAME a cluster user allowed to deploy # HARPER_CLI_PASSWORD that user's password # -# Public repo and want zero cluster-side auth, or prefer building in CI and publishing to a registry? -# See the "Deployment" section of the README for those alternatives. +# Public repo? Drop `credential=github.com` from the `deploy` script — no cluster-side auth needed. +# See the "Deployment" section of the README for details. name: Deploy to Harper Fabric on: workflow_dispatch: diff --git a/template-react-ts-ssr/package.json b/template-react-ts-ssr/package.json index 43d00e6..2401817 100644 --- a/template-react-ts-ssr/package.json +++ b/template-react-ts-ssr/package.json @@ -13,7 +13,7 @@ "test": "node --test test/*.test.ts", "test:watch": "node --watch --test test/*.test.ts", "build": "vite build", - "deploy": "harper deploy by_ref=true restart=true replicated=true", + "deploy": "harper deploy by_ref=true credential=github.com restart=true replicated=true", "deploy:setup": "harper deploy setup=true" }, "dependencies": { diff --git a/template-react-ts/README.md b/template-react-ts/README.md index 9af4e5f..eaeff6f 100644 --- a/template-react-ts/README.md +++ b/template-react-ts/README.md @@ -111,7 +111,7 @@ Take a look at the [default configuration](./config.yaml), which specifies how f ## Deployment -Deploy your app to a Harper cluster **by reference**: rather than uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit. +Deploy your app to a Harper cluster **by reference**: instead of uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit. First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in, and create a cluster. Then log your local CLI in to it: @@ -119,15 +119,17 @@ First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log i harper login ``` -### One-time setup +### One-time setup (private repos) -So the cluster can clone your (private) repository, register a read-only SSH **deploy key**: +So the cluster can clone your private repository, give it a read-only token — sealed on your machine, stored encrypted: ```sh npm run deploy:setup ``` -This generates the key, registers it with your cluster, and prints a public key to add to your repository under **Settings → Deploy keys**. A deploy key is scoped to this one repository and keeps working even if the person who created it leaves. (It uses Harper's `add_ssh_key`, available on Harper Pro / Fabric.) +This fetches your cluster's public key, has you provide a GitHub token (a fine-grained PAT with **Contents: Read-only**, or your `gh` CLI session), **encrypts it locally**, and stores only the ciphertext in the cluster's secret store. The plaintext never leaves your machine; the cluster decrypts it in memory only while cloning. Because the token is durable, rollbacks keep working for as long as it's valid. + +> Public repo? Skip this step and drop `credential=github.com` from the `deploy` script — no credential is needed. ### Deploy @@ -135,7 +137,7 @@ This generates the key, registers it with your cluster, and prints a public key npm run deploy ``` -This deploys the current commit — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again. +This deploys the current commit over `git+https` — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again. ### Deploy automatically from CI @@ -151,12 +153,11 @@ Add these repository secrets first, under **Settings → Secrets and variables - `CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`) - `HARPER_CLI_USERNAME` and `HARPER_CLI_PASSWORD` — a cluster user allowed to deploy -### Other options +The clone credential already lives in the cluster from `npm run deploy:setup`, so CI never handles a token itself. -- **Public repository?** Skip the deploy key and let Harper clone over HTTPS (`git+https://…#`) with no cluster-side credentials. -- **Prefer to build in CI** instead of on your Harper nodes? Publish your app to a registry such as GitHub Packages and deploy it by version using `registryAuth`. +### Private npm dependencies -See the [Harper deployment docs](https://docs.harperdb.io/reference/v5/components/applications#deploy_component) for both. +If your app depends on private npm packages, run `npm run deploy:setup` again and choose the npm registry — the same sealed-token flow, stored as a separate credential. ## Keep Going! diff --git a/template-react-ts/_github/workflows/deploy.yaml b/template-react-ts/_github/workflows/deploy.yaml index c73ffd9..16e83aa 100644 --- a/template-react-ts/_github/workflows/deploy.yaml +++ b/template-react-ts/_github/workflows/deploy.yaml @@ -2,16 +2,17 @@ # (`npm run deploy`). # # Runs on a version tag (e.g. `git tag v1.2.3 && git push --tags`) or manually. The Harper cluster -# fetches the tagged commit over SSH (pinned by its exact SHA, so peers can't diverge on a moved tag) -# using the read-only deploy key you registered once with `npm run deploy:setup`. +# fetches the tagged commit over git+https (pinned by its exact SHA, so peers can't diverge on a +# moved tag), authenticating a private clone with the encrypted token you sealed once via +# `npm run deploy:setup`. The credential lives on the cluster, so this workflow handles no token. # # Required repository secrets (Settings → Secrets and variables → Actions): # CLI_TARGET your cluster's operations URL, e.g. https://my-cluster.harperdb.io:9925 # HARPER_CLI_USERNAME a cluster user allowed to deploy # HARPER_CLI_PASSWORD that user's password # -# Public repo and want zero cluster-side auth, or prefer building in CI and publishing to a registry? -# See the "Deployment" section of the README for those alternatives. +# Public repo? Drop `credential=github.com` from the `deploy` script — no cluster-side auth needed. +# See the "Deployment" section of the README for details. name: Deploy to Harper Fabric on: workflow_dispatch: diff --git a/template-react-ts/package.json b/template-react-ts/package.json index 43d00e6..2401817 100644 --- a/template-react-ts/package.json +++ b/template-react-ts/package.json @@ -13,7 +13,7 @@ "test": "node --test test/*.test.ts", "test:watch": "node --watch --test test/*.test.ts", "build": "vite build", - "deploy": "harper deploy by_ref=true restart=true replicated=true", + "deploy": "harper deploy by_ref=true credential=github.com restart=true replicated=true", "deploy:setup": "harper deploy setup=true" }, "dependencies": { diff --git a/template-react/README.md b/template-react/README.md index 893ffe2..1da0137 100644 --- a/template-react/README.md +++ b/template-react/README.md @@ -103,7 +103,7 @@ Take a look at the [default configuration](./config.yaml), which specifies how f ## Deployment -Deploy your app to a Harper cluster **by reference**: rather than uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit. +Deploy your app to a Harper cluster **by reference**: instead of uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit. First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in, and create a cluster. Then log your local CLI in to it: @@ -111,15 +111,17 @@ First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log i harper login ``` -### One-time setup +### One-time setup (private repos) -So the cluster can clone your (private) repository, register a read-only SSH **deploy key**: +So the cluster can clone your private repository, give it a read-only token — sealed on your machine, stored encrypted: ```sh npm run deploy:setup ``` -This generates the key, registers it with your cluster, and prints a public key to add to your repository under **Settings → Deploy keys**. A deploy key is scoped to this one repository and keeps working even if the person who created it leaves. (It uses Harper's `add_ssh_key`, available on Harper Pro / Fabric.) +This fetches your cluster's public key, has you provide a GitHub token (a fine-grained PAT with **Contents: Read-only**, or your `gh` CLI session), **encrypts it locally**, and stores only the ciphertext in the cluster's secret store. The plaintext never leaves your machine; the cluster decrypts it in memory only while cloning. Because the token is durable, rollbacks keep working for as long as it's valid. + +> Public repo? Skip this step and drop `credential=github.com` from the `deploy` script — no credential is needed. ### Deploy @@ -127,7 +129,7 @@ This generates the key, registers it with your cluster, and prints a public key npm run deploy ``` -This deploys the current commit — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again. +This deploys the current commit over `git+https` — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again. ### Deploy automatically from CI @@ -143,12 +145,11 @@ Add these repository secrets first, under **Settings → Secrets and variables - `CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`) - `HARPER_CLI_USERNAME` and `HARPER_CLI_PASSWORD` — a cluster user allowed to deploy -### Other options +The clone credential already lives in the cluster from `npm run deploy:setup`, so CI never handles a token itself. -- **Public repository?** Skip the deploy key and let Harper clone over HTTPS (`git+https://…#`) with no cluster-side credentials. -- **Prefer to build in CI** instead of on your Harper nodes? Publish your app to a registry such as GitHub Packages and deploy it by version using `registryAuth`. +### Private npm dependencies -See the [Harper deployment docs](https://docs.harperdb.io/reference/v5/components/applications#deploy_component) for both. +If your app depends on private npm packages, run `npm run deploy:setup` again and choose the npm registry — the same sealed-token flow, stored as a separate credential. ## Keep Going! diff --git a/template-react/_github/workflows/deploy.yaml b/template-react/_github/workflows/deploy.yaml index c73ffd9..16e83aa 100644 --- a/template-react/_github/workflows/deploy.yaml +++ b/template-react/_github/workflows/deploy.yaml @@ -2,16 +2,17 @@ # (`npm run deploy`). # # Runs on a version tag (e.g. `git tag v1.2.3 && git push --tags`) or manually. The Harper cluster -# fetches the tagged commit over SSH (pinned by its exact SHA, so peers can't diverge on a moved tag) -# using the read-only deploy key you registered once with `npm run deploy:setup`. +# fetches the tagged commit over git+https (pinned by its exact SHA, so peers can't diverge on a +# moved tag), authenticating a private clone with the encrypted token you sealed once via +# `npm run deploy:setup`. The credential lives on the cluster, so this workflow handles no token. # # Required repository secrets (Settings → Secrets and variables → Actions): # CLI_TARGET your cluster's operations URL, e.g. https://my-cluster.harperdb.io:9925 # HARPER_CLI_USERNAME a cluster user allowed to deploy # HARPER_CLI_PASSWORD that user's password # -# Public repo and want zero cluster-side auth, or prefer building in CI and publishing to a registry? -# See the "Deployment" section of the README for those alternatives. +# Public repo? Drop `credential=github.com` from the `deploy` script — no cluster-side auth needed. +# See the "Deployment" section of the README for details. name: Deploy to Harper Fabric on: workflow_dispatch: diff --git a/template-react/package.json b/template-react/package.json index 6ded932..41fc54a 100644 --- a/template-react/package.json +++ b/template-react/package.json @@ -13,7 +13,7 @@ "test": "node --test test/*.test.js", "test:watch": "node --watch --test test/*.test.js", "build": "vite build", - "deploy": "harper deploy by_ref=true restart=true replicated=true", + "deploy": "harper deploy by_ref=true credential=github.com restart=true replicated=true", "deploy:setup": "harper deploy setup=true" }, "dependencies": { diff --git a/template-vanilla-ts/README.md b/template-vanilla-ts/README.md index 6556313..e899205 100644 --- a/template-vanilla-ts/README.md +++ b/template-vanilla-ts/README.md @@ -111,7 +111,7 @@ Take a look at the [default configuration](./config.yaml), which specifies how f ## Deployment -Deploy your app to a Harper cluster **by reference**: rather than uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit. +Deploy your app to a Harper cluster **by reference**: instead of uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit. First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in, and create a cluster. Then log your local CLI in to it: @@ -119,15 +119,17 @@ First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log i harper login ``` -### One-time setup +### One-time setup (private repos) -So the cluster can clone your (private) repository, register a read-only SSH **deploy key**: +So the cluster can clone your private repository, give it a read-only token — sealed on your machine, stored encrypted: ```sh npm run deploy:setup ``` -This generates the key, registers it with your cluster, and prints a public key to add to your repository under **Settings → Deploy keys**. A deploy key is scoped to this one repository and keeps working even if the person who created it leaves. (It uses Harper's `add_ssh_key`, available on Harper Pro / Fabric.) +This fetches your cluster's public key, has you provide a GitHub token (a fine-grained PAT with **Contents: Read-only**, or your `gh` CLI session), **encrypts it locally**, and stores only the ciphertext in the cluster's secret store. The plaintext never leaves your machine; the cluster decrypts it in memory only while cloning. Because the token is durable, rollbacks keep working for as long as it's valid. + +> Public repo? Skip this step and drop `credential=github.com` from the `deploy` script — no credential is needed. ### Deploy @@ -135,7 +137,7 @@ This generates the key, registers it with your cluster, and prints a public key npm run deploy ``` -This deploys the current commit — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again. +This deploys the current commit over `git+https` — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again. ### Deploy automatically from CI @@ -151,12 +153,11 @@ Add these repository secrets first, under **Settings → Secrets and variables - `CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`) - `HARPER_CLI_USERNAME` and `HARPER_CLI_PASSWORD` — a cluster user allowed to deploy -### Other options +The clone credential already lives in the cluster from `npm run deploy:setup`, so CI never handles a token itself. -- **Public repository?** Skip the deploy key and let Harper clone over HTTPS (`git+https://…#`) with no cluster-side credentials. -- **Prefer to build in CI** instead of on your Harper nodes? Publish your app to a registry such as GitHub Packages and deploy it by version using `registryAuth`. +### Private npm dependencies -See the [Harper deployment docs](https://docs.harperdb.io/reference/v5/components/applications#deploy_component) for both. +If your app depends on private npm packages, run `npm run deploy:setup` again and choose the npm registry — the same sealed-token flow, stored as a separate credential. ## Keep Going! diff --git a/template-vanilla-ts/_github/workflows/deploy.yaml b/template-vanilla-ts/_github/workflows/deploy.yaml index c73ffd9..16e83aa 100644 --- a/template-vanilla-ts/_github/workflows/deploy.yaml +++ b/template-vanilla-ts/_github/workflows/deploy.yaml @@ -2,16 +2,17 @@ # (`npm run deploy`). # # Runs on a version tag (e.g. `git tag v1.2.3 && git push --tags`) or manually. The Harper cluster -# fetches the tagged commit over SSH (pinned by its exact SHA, so peers can't diverge on a moved tag) -# using the read-only deploy key you registered once with `npm run deploy:setup`. +# fetches the tagged commit over git+https (pinned by its exact SHA, so peers can't diverge on a +# moved tag), authenticating a private clone with the encrypted token you sealed once via +# `npm run deploy:setup`. The credential lives on the cluster, so this workflow handles no token. # # Required repository secrets (Settings → Secrets and variables → Actions): # CLI_TARGET your cluster's operations URL, e.g. https://my-cluster.harperdb.io:9925 # HARPER_CLI_USERNAME a cluster user allowed to deploy # HARPER_CLI_PASSWORD that user's password # -# Public repo and want zero cluster-side auth, or prefer building in CI and publishing to a registry? -# See the "Deployment" section of the README for those alternatives. +# Public repo? Drop `credential=github.com` from the `deploy` script — no cluster-side auth needed. +# See the "Deployment" section of the README for details. name: Deploy to Harper Fabric on: workflow_dispatch: diff --git a/template-vanilla-ts/package.json b/template-vanilla-ts/package.json index 13f6eff..5b19f11 100644 --- a/template-vanilla-ts/package.json +++ b/template-vanilla-ts/package.json @@ -12,7 +12,7 @@ "format": "prettier --write .", "test": "node --test test/*.test.js", "test:watch": "node --watch --test test/*.test.js", - "deploy": "harper deploy by_ref=true restart=true replicated=true", + "deploy": "harper deploy by_ref=true credential=github.com restart=true replicated=true", "deploy:setup": "harper deploy setup=true" }, "devDependencies": { diff --git a/template-vanilla/README.md b/template-vanilla/README.md index d8a32ee..51bd5a9 100644 --- a/template-vanilla/README.md +++ b/template-vanilla/README.md @@ -103,7 +103,7 @@ Take a look at the [default configuration](./config.yaml), which specifies how f ## Deployment -Deploy your app to a Harper cluster **by reference**: rather than uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit. +Deploy your app to a Harper cluster **by reference**: instead of uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit. First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in, and create a cluster. Then log your local CLI in to it: @@ -111,15 +111,17 @@ First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log i harper login ``` -### One-time setup +### One-time setup (private repos) -So the cluster can clone your (private) repository, register a read-only SSH **deploy key**: +So the cluster can clone your private repository, give it a read-only token — sealed on your machine, stored encrypted: ```sh npm run deploy:setup ``` -This generates the key, registers it with your cluster, and prints a public key to add to your repository under **Settings → Deploy keys**. A deploy key is scoped to this one repository and keeps working even if the person who created it leaves. (It uses Harper's `add_ssh_key`, available on Harper Pro / Fabric.) +This fetches your cluster's public key, has you provide a GitHub token (a fine-grained PAT with **Contents: Read-only**, or your `gh` CLI session), **encrypts it locally**, and stores only the ciphertext in the cluster's secret store. The plaintext never leaves your machine; the cluster decrypts it in memory only while cloning. Because the token is durable, rollbacks keep working for as long as it's valid. + +> Public repo? Skip this step and drop `credential=github.com` from the `deploy` script — no credential is needed. ### Deploy @@ -127,7 +129,7 @@ This generates the key, registers it with your cluster, and prints a public key npm run deploy ``` -This deploys the current commit — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again. +This deploys the current commit over `git+https` — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again. ### Deploy automatically from CI @@ -143,12 +145,11 @@ Add these repository secrets first, under **Settings → Secrets and variables - `CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`) - `HARPER_CLI_USERNAME` and `HARPER_CLI_PASSWORD` — a cluster user allowed to deploy -### Other options +The clone credential already lives in the cluster from `npm run deploy:setup`, so CI never handles a token itself. -- **Public repository?** Skip the deploy key and let Harper clone over HTTPS (`git+https://…#`) with no cluster-side credentials. -- **Prefer to build in CI** instead of on your Harper nodes? Publish your app to a registry such as GitHub Packages and deploy it by version using `registryAuth`. +### Private npm dependencies -See the [Harper deployment docs](https://docs.harperdb.io/reference/v5/components/applications#deploy_component) for both. +If your app depends on private npm packages, run `npm run deploy:setup` again and choose the npm registry — the same sealed-token flow, stored as a separate credential. ## Keep Going! diff --git a/template-vanilla/_github/workflows/deploy.yaml b/template-vanilla/_github/workflows/deploy.yaml index c73ffd9..16e83aa 100644 --- a/template-vanilla/_github/workflows/deploy.yaml +++ b/template-vanilla/_github/workflows/deploy.yaml @@ -2,16 +2,17 @@ # (`npm run deploy`). # # Runs on a version tag (e.g. `git tag v1.2.3 && git push --tags`) or manually. The Harper cluster -# fetches the tagged commit over SSH (pinned by its exact SHA, so peers can't diverge on a moved tag) -# using the read-only deploy key you registered once with `npm run deploy:setup`. +# fetches the tagged commit over git+https (pinned by its exact SHA, so peers can't diverge on a +# moved tag), authenticating a private clone with the encrypted token you sealed once via +# `npm run deploy:setup`. The credential lives on the cluster, so this workflow handles no token. # # Required repository secrets (Settings → Secrets and variables → Actions): # CLI_TARGET your cluster's operations URL, e.g. https://my-cluster.harperdb.io:9925 # HARPER_CLI_USERNAME a cluster user allowed to deploy # HARPER_CLI_PASSWORD that user's password # -# Public repo and want zero cluster-side auth, or prefer building in CI and publishing to a registry? -# See the "Deployment" section of the README for those alternatives. +# Public repo? Drop `credential=github.com` from the `deploy` script — no cluster-side auth needed. +# See the "Deployment" section of the README for details. name: Deploy to Harper Fabric on: workflow_dispatch: diff --git a/template-vanilla/package.json b/template-vanilla/package.json index 13f6eff..5b19f11 100644 --- a/template-vanilla/package.json +++ b/template-vanilla/package.json @@ -12,7 +12,7 @@ "format": "prettier --write .", "test": "node --test test/*.test.js", "test:watch": "node --watch --test test/*.test.js", - "deploy": "harper deploy by_ref=true restart=true replicated=true", + "deploy": "harper deploy by_ref=true credential=github.com restart=true replicated=true", "deploy:setup": "harper deploy setup=true" }, "devDependencies": { diff --git a/template-vue-ssr/README.md b/template-vue-ssr/README.md index 893ffe2..1da0137 100644 --- a/template-vue-ssr/README.md +++ b/template-vue-ssr/README.md @@ -103,7 +103,7 @@ Take a look at the [default configuration](./config.yaml), which specifies how f ## Deployment -Deploy your app to a Harper cluster **by reference**: rather than uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit. +Deploy your app to a Harper cluster **by reference**: instead of uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit. First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in, and create a cluster. Then log your local CLI in to it: @@ -111,15 +111,17 @@ First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log i harper login ``` -### One-time setup +### One-time setup (private repos) -So the cluster can clone your (private) repository, register a read-only SSH **deploy key**: +So the cluster can clone your private repository, give it a read-only token — sealed on your machine, stored encrypted: ```sh npm run deploy:setup ``` -This generates the key, registers it with your cluster, and prints a public key to add to your repository under **Settings → Deploy keys**. A deploy key is scoped to this one repository and keeps working even if the person who created it leaves. (It uses Harper's `add_ssh_key`, available on Harper Pro / Fabric.) +This fetches your cluster's public key, has you provide a GitHub token (a fine-grained PAT with **Contents: Read-only**, or your `gh` CLI session), **encrypts it locally**, and stores only the ciphertext in the cluster's secret store. The plaintext never leaves your machine; the cluster decrypts it in memory only while cloning. Because the token is durable, rollbacks keep working for as long as it's valid. + +> Public repo? Skip this step and drop `credential=github.com` from the `deploy` script — no credential is needed. ### Deploy @@ -127,7 +129,7 @@ This generates the key, registers it with your cluster, and prints a public key npm run deploy ``` -This deploys the current commit — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again. +This deploys the current commit over `git+https` — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again. ### Deploy automatically from CI @@ -143,12 +145,11 @@ Add these repository secrets first, under **Settings → Secrets and variables - `CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`) - `HARPER_CLI_USERNAME` and `HARPER_CLI_PASSWORD` — a cluster user allowed to deploy -### Other options +The clone credential already lives in the cluster from `npm run deploy:setup`, so CI never handles a token itself. -- **Public repository?** Skip the deploy key and let Harper clone over HTTPS (`git+https://…#`) with no cluster-side credentials. -- **Prefer to build in CI** instead of on your Harper nodes? Publish your app to a registry such as GitHub Packages and deploy it by version using `registryAuth`. +### Private npm dependencies -See the [Harper deployment docs](https://docs.harperdb.io/reference/v5/components/applications#deploy_component) for both. +If your app depends on private npm packages, run `npm run deploy:setup` again and choose the npm registry — the same sealed-token flow, stored as a separate credential. ## Keep Going! diff --git a/template-vue-ssr/_github/workflows/deploy.yaml b/template-vue-ssr/_github/workflows/deploy.yaml index c73ffd9..16e83aa 100644 --- a/template-vue-ssr/_github/workflows/deploy.yaml +++ b/template-vue-ssr/_github/workflows/deploy.yaml @@ -2,16 +2,17 @@ # (`npm run deploy`). # # Runs on a version tag (e.g. `git tag v1.2.3 && git push --tags`) or manually. The Harper cluster -# fetches the tagged commit over SSH (pinned by its exact SHA, so peers can't diverge on a moved tag) -# using the read-only deploy key you registered once with `npm run deploy:setup`. +# fetches the tagged commit over git+https (pinned by its exact SHA, so peers can't diverge on a +# moved tag), authenticating a private clone with the encrypted token you sealed once via +# `npm run deploy:setup`. The credential lives on the cluster, so this workflow handles no token. # # Required repository secrets (Settings → Secrets and variables → Actions): # CLI_TARGET your cluster's operations URL, e.g. https://my-cluster.harperdb.io:9925 # HARPER_CLI_USERNAME a cluster user allowed to deploy # HARPER_CLI_PASSWORD that user's password # -# Public repo and want zero cluster-side auth, or prefer building in CI and publishing to a registry? -# See the "Deployment" section of the README for those alternatives. +# Public repo? Drop `credential=github.com` from the `deploy` script — no cluster-side auth needed. +# See the "Deployment" section of the README for details. name: Deploy to Harper Fabric on: workflow_dispatch: diff --git a/template-vue-ssr/package.json b/template-vue-ssr/package.json index 8946f8f..b5fac98 100644 --- a/template-vue-ssr/package.json +++ b/template-vue-ssr/package.json @@ -13,7 +13,7 @@ "test": "node --test test/*.test.js", "test:watch": "node --watch --test test/*.test.js", "build": "vite build", - "deploy": "harper deploy by_ref=true restart=true replicated=true", + "deploy": "harper deploy by_ref=true credential=github.com restart=true replicated=true", "deploy:setup": "harper deploy setup=true" }, "dependencies": { diff --git a/template-vue-ts-ssr/README.md b/template-vue-ts-ssr/README.md index 9af4e5f..eaeff6f 100644 --- a/template-vue-ts-ssr/README.md +++ b/template-vue-ts-ssr/README.md @@ -111,7 +111,7 @@ Take a look at the [default configuration](./config.yaml), which specifies how f ## Deployment -Deploy your app to a Harper cluster **by reference**: rather than uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit. +Deploy your app to a Harper cluster **by reference**: instead of uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit. First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in, and create a cluster. Then log your local CLI in to it: @@ -119,15 +119,17 @@ First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log i harper login ``` -### One-time setup +### One-time setup (private repos) -So the cluster can clone your (private) repository, register a read-only SSH **deploy key**: +So the cluster can clone your private repository, give it a read-only token — sealed on your machine, stored encrypted: ```sh npm run deploy:setup ``` -This generates the key, registers it with your cluster, and prints a public key to add to your repository under **Settings → Deploy keys**. A deploy key is scoped to this one repository and keeps working even if the person who created it leaves. (It uses Harper's `add_ssh_key`, available on Harper Pro / Fabric.) +This fetches your cluster's public key, has you provide a GitHub token (a fine-grained PAT with **Contents: Read-only**, or your `gh` CLI session), **encrypts it locally**, and stores only the ciphertext in the cluster's secret store. The plaintext never leaves your machine; the cluster decrypts it in memory only while cloning. Because the token is durable, rollbacks keep working for as long as it's valid. + +> Public repo? Skip this step and drop `credential=github.com` from the `deploy` script — no credential is needed. ### Deploy @@ -135,7 +137,7 @@ This generates the key, registers it with your cluster, and prints a public key npm run deploy ``` -This deploys the current commit — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again. +This deploys the current commit over `git+https` — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again. ### Deploy automatically from CI @@ -151,12 +153,11 @@ Add these repository secrets first, under **Settings → Secrets and variables - `CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`) - `HARPER_CLI_USERNAME` and `HARPER_CLI_PASSWORD` — a cluster user allowed to deploy -### Other options +The clone credential already lives in the cluster from `npm run deploy:setup`, so CI never handles a token itself. -- **Public repository?** Skip the deploy key and let Harper clone over HTTPS (`git+https://…#`) with no cluster-side credentials. -- **Prefer to build in CI** instead of on your Harper nodes? Publish your app to a registry such as GitHub Packages and deploy it by version using `registryAuth`. +### Private npm dependencies -See the [Harper deployment docs](https://docs.harperdb.io/reference/v5/components/applications#deploy_component) for both. +If your app depends on private npm packages, run `npm run deploy:setup` again and choose the npm registry — the same sealed-token flow, stored as a separate credential. ## Keep Going! diff --git a/template-vue-ts-ssr/_github/workflows/deploy.yaml b/template-vue-ts-ssr/_github/workflows/deploy.yaml index c73ffd9..16e83aa 100644 --- a/template-vue-ts-ssr/_github/workflows/deploy.yaml +++ b/template-vue-ts-ssr/_github/workflows/deploy.yaml @@ -2,16 +2,17 @@ # (`npm run deploy`). # # Runs on a version tag (e.g. `git tag v1.2.3 && git push --tags`) or manually. The Harper cluster -# fetches the tagged commit over SSH (pinned by its exact SHA, so peers can't diverge on a moved tag) -# using the read-only deploy key you registered once with `npm run deploy:setup`. +# fetches the tagged commit over git+https (pinned by its exact SHA, so peers can't diverge on a +# moved tag), authenticating a private clone with the encrypted token you sealed once via +# `npm run deploy:setup`. The credential lives on the cluster, so this workflow handles no token. # # Required repository secrets (Settings → Secrets and variables → Actions): # CLI_TARGET your cluster's operations URL, e.g. https://my-cluster.harperdb.io:9925 # HARPER_CLI_USERNAME a cluster user allowed to deploy # HARPER_CLI_PASSWORD that user's password # -# Public repo and want zero cluster-side auth, or prefer building in CI and publishing to a registry? -# See the "Deployment" section of the README for those alternatives. +# Public repo? Drop `credential=github.com` from the `deploy` script — no cluster-side auth needed. +# See the "Deployment" section of the README for details. name: Deploy to Harper Fabric on: workflow_dispatch: diff --git a/template-vue-ts-ssr/package.json b/template-vue-ts-ssr/package.json index 4cc9723..faab90b 100644 --- a/template-vue-ts-ssr/package.json +++ b/template-vue-ts-ssr/package.json @@ -13,7 +13,7 @@ "test": "node --test test/*.test.ts", "test:watch": "node --watch --test test/*.test.ts", "build": "vite build", - "deploy": "harper deploy by_ref=true restart=true replicated=true", + "deploy": "harper deploy by_ref=true credential=github.com restart=true replicated=true", "deploy:setup": "harper deploy setup=true" }, "dependencies": { diff --git a/template-vue-ts/README.md b/template-vue-ts/README.md index 9af4e5f..eaeff6f 100644 --- a/template-vue-ts/README.md +++ b/template-vue-ts/README.md @@ -111,7 +111,7 @@ Take a look at the [default configuration](./config.yaml), which specifies how f ## Deployment -Deploy your app to a Harper cluster **by reference**: rather than uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit. +Deploy your app to a Harper cluster **by reference**: instead of uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit. First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in, and create a cluster. Then log your local CLI in to it: @@ -119,15 +119,17 @@ First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log i harper login ``` -### One-time setup +### One-time setup (private repos) -So the cluster can clone your (private) repository, register a read-only SSH **deploy key**: +So the cluster can clone your private repository, give it a read-only token — sealed on your machine, stored encrypted: ```sh npm run deploy:setup ``` -This generates the key, registers it with your cluster, and prints a public key to add to your repository under **Settings → Deploy keys**. A deploy key is scoped to this one repository and keeps working even if the person who created it leaves. (It uses Harper's `add_ssh_key`, available on Harper Pro / Fabric.) +This fetches your cluster's public key, has you provide a GitHub token (a fine-grained PAT with **Contents: Read-only**, or your `gh` CLI session), **encrypts it locally**, and stores only the ciphertext in the cluster's secret store. The plaintext never leaves your machine; the cluster decrypts it in memory only while cloning. Because the token is durable, rollbacks keep working for as long as it's valid. + +> Public repo? Skip this step and drop `credential=github.com` from the `deploy` script — no credential is needed. ### Deploy @@ -135,7 +137,7 @@ This generates the key, registers it with your cluster, and prints a public key npm run deploy ``` -This deploys the current commit — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again. +This deploys the current commit over `git+https` — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again. ### Deploy automatically from CI @@ -151,12 +153,11 @@ Add these repository secrets first, under **Settings → Secrets and variables - `CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`) - `HARPER_CLI_USERNAME` and `HARPER_CLI_PASSWORD` — a cluster user allowed to deploy -### Other options +The clone credential already lives in the cluster from `npm run deploy:setup`, so CI never handles a token itself. -- **Public repository?** Skip the deploy key and let Harper clone over HTTPS (`git+https://…#`) with no cluster-side credentials. -- **Prefer to build in CI** instead of on your Harper nodes? Publish your app to a registry such as GitHub Packages and deploy it by version using `registryAuth`. +### Private npm dependencies -See the [Harper deployment docs](https://docs.harperdb.io/reference/v5/components/applications#deploy_component) for both. +If your app depends on private npm packages, run `npm run deploy:setup` again and choose the npm registry — the same sealed-token flow, stored as a separate credential. ## Keep Going! diff --git a/template-vue-ts/_github/workflows/deploy.yaml b/template-vue-ts/_github/workflows/deploy.yaml index c73ffd9..16e83aa 100644 --- a/template-vue-ts/_github/workflows/deploy.yaml +++ b/template-vue-ts/_github/workflows/deploy.yaml @@ -2,16 +2,17 @@ # (`npm run deploy`). # # Runs on a version tag (e.g. `git tag v1.2.3 && git push --tags`) or manually. The Harper cluster -# fetches the tagged commit over SSH (pinned by its exact SHA, so peers can't diverge on a moved tag) -# using the read-only deploy key you registered once with `npm run deploy:setup`. +# fetches the tagged commit over git+https (pinned by its exact SHA, so peers can't diverge on a +# moved tag), authenticating a private clone with the encrypted token you sealed once via +# `npm run deploy:setup`. The credential lives on the cluster, so this workflow handles no token. # # Required repository secrets (Settings → Secrets and variables → Actions): # CLI_TARGET your cluster's operations URL, e.g. https://my-cluster.harperdb.io:9925 # HARPER_CLI_USERNAME a cluster user allowed to deploy # HARPER_CLI_PASSWORD that user's password # -# Public repo and want zero cluster-side auth, or prefer building in CI and publishing to a registry? -# See the "Deployment" section of the README for those alternatives. +# Public repo? Drop `credential=github.com` from the `deploy` script — no cluster-side auth needed. +# See the "Deployment" section of the README for details. name: Deploy to Harper Fabric on: workflow_dispatch: diff --git a/template-vue-ts/package.json b/template-vue-ts/package.json index 4cc9723..faab90b 100644 --- a/template-vue-ts/package.json +++ b/template-vue-ts/package.json @@ -13,7 +13,7 @@ "test": "node --test test/*.test.ts", "test:watch": "node --watch --test test/*.test.ts", "build": "vite build", - "deploy": "harper deploy by_ref=true restart=true replicated=true", + "deploy": "harper deploy by_ref=true credential=github.com restart=true replicated=true", "deploy:setup": "harper deploy setup=true" }, "dependencies": { diff --git a/template-vue/README.md b/template-vue/README.md index 893ffe2..1da0137 100644 --- a/template-vue/README.md +++ b/template-vue/README.md @@ -103,7 +103,7 @@ Take a look at the [default configuration](./config.yaml), which specifies how f ## Deployment -Deploy your app to a Harper cluster **by reference**: rather than uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit. +Deploy your app to a Harper cluster **by reference**: instead of uploading a snapshot of your files, you tell Harper which commit of your GitHub repository to run, pinned by its exact commit SHA. Re-deploying the same commit is repeatable, and rolling back is just deploying an older commit. First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in, and create a cluster. Then log your local CLI in to it: @@ -111,15 +111,17 @@ First, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log i harper login ``` -### One-time setup +### One-time setup (private repos) -So the cluster can clone your (private) repository, register a read-only SSH **deploy key**: +So the cluster can clone your private repository, give it a read-only token — sealed on your machine, stored encrypted: ```sh npm run deploy:setup ``` -This generates the key, registers it with your cluster, and prints a public key to add to your repository under **Settings → Deploy keys**. A deploy key is scoped to this one repository and keeps working even if the person who created it leaves. (It uses Harper's `add_ssh_key`, available on Harper Pro / Fabric.) +This fetches your cluster's public key, has you provide a GitHub token (a fine-grained PAT with **Contents: Read-only**, or your `gh` CLI session), **encrypts it locally**, and stores only the ciphertext in the cluster's secret store. The plaintext never leaves your machine; the cluster decrypts it in memory only while cloning. Because the token is durable, rollbacks keep working for as long as it's valid. + +> Public repo? Skip this step and drop `credential=github.com` from the `deploy` script — no credential is needed. ### Deploy @@ -127,7 +129,7 @@ This generates the key, registers it with your cluster, and prints a public key npm run deploy ``` -This deploys the current commit — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again. +This deploys the current commit over `git+https` — commit and push first, since the cluster clones from GitHub and only sees pushed commits. To roll back, check out an older commit and run it again. ### Deploy automatically from CI @@ -143,12 +145,11 @@ Add these repository secrets first, under **Settings → Secrets and variables - `CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`) - `HARPER_CLI_USERNAME` and `HARPER_CLI_PASSWORD` — a cluster user allowed to deploy -### Other options +The clone credential already lives in the cluster from `npm run deploy:setup`, so CI never handles a token itself. -- **Public repository?** Skip the deploy key and let Harper clone over HTTPS (`git+https://…#`) with no cluster-side credentials. -- **Prefer to build in CI** instead of on your Harper nodes? Publish your app to a registry such as GitHub Packages and deploy it by version using `registryAuth`. +### Private npm dependencies -See the [Harper deployment docs](https://docs.harperdb.io/reference/v5/components/applications#deploy_component) for both. +If your app depends on private npm packages, run `npm run deploy:setup` again and choose the npm registry — the same sealed-token flow, stored as a separate credential. ## Keep Going! diff --git a/template-vue/_github/workflows/deploy.yaml b/template-vue/_github/workflows/deploy.yaml index c73ffd9..16e83aa 100644 --- a/template-vue/_github/workflows/deploy.yaml +++ b/template-vue/_github/workflows/deploy.yaml @@ -2,16 +2,17 @@ # (`npm run deploy`). # # Runs on a version tag (e.g. `git tag v1.2.3 && git push --tags`) or manually. The Harper cluster -# fetches the tagged commit over SSH (pinned by its exact SHA, so peers can't diverge on a moved tag) -# using the read-only deploy key you registered once with `npm run deploy:setup`. +# fetches the tagged commit over git+https (pinned by its exact SHA, so peers can't diverge on a +# moved tag), authenticating a private clone with the encrypted token you sealed once via +# `npm run deploy:setup`. The credential lives on the cluster, so this workflow handles no token. # # Required repository secrets (Settings → Secrets and variables → Actions): # CLI_TARGET your cluster's operations URL, e.g. https://my-cluster.harperdb.io:9925 # HARPER_CLI_USERNAME a cluster user allowed to deploy # HARPER_CLI_PASSWORD that user's password # -# Public repo and want zero cluster-side auth, or prefer building in CI and publishing to a registry? -# See the "Deployment" section of the README for those alternatives. +# Public repo? Drop `credential=github.com` from the `deploy` script — no cluster-side auth needed. +# See the "Deployment" section of the README for details. name: Deploy to Harper Fabric on: workflow_dispatch: diff --git a/template-vue/package.json b/template-vue/package.json index 8946f8f..b5fac98 100644 --- a/template-vue/package.json +++ b/template-vue/package.json @@ -13,7 +13,7 @@ "test": "node --test test/*.test.js", "test:watch": "node --watch --test test/*.test.js", "build": "vite build", - "deploy": "harper deploy by_ref=true restart=true replicated=true", + "deploy": "harper deploy by_ref=true credential=github.com restart=true replicated=true", "deploy:setup": "harper deploy setup=true" }, "dependencies": { diff --git a/template.tests/template.test.js b/template.tests/template.test.js index b6582d9..0079fa6 100644 --- a/template.tests/template.test.js +++ b/template.tests/template.test.js @@ -86,7 +86,9 @@ describe('Integration tests', () => { // (no per-project scripts). expect(fs.existsSync(path.join(targetDir, '.github', 'workflows', 'deploy.yaml'))).toBe(true); expect(fs.existsSync(path.join(targetDir, 'scripts', 'deploy.mjs'))).toBe(false); - expect(pkgJson.scripts.deploy).toBe('harper deploy by_ref=true restart=true replicated=true'); + expect(pkgJson.scripts.deploy).toBe( + 'harper deploy by_ref=true credential=github.com restart=true replicated=true', + ); expect(pkgJson.scripts['deploy:setup']).toBe('harper deploy setup=true'); }); } diff --git a/templates-shared/all/_github/workflows/deploy.yaml b/templates-shared/all/_github/workflows/deploy.yaml index c73ffd9..16e83aa 100644 --- a/templates-shared/all/_github/workflows/deploy.yaml +++ b/templates-shared/all/_github/workflows/deploy.yaml @@ -2,16 +2,17 @@ # (`npm run deploy`). # # Runs on a version tag (e.g. `git tag v1.2.3 && git push --tags`) or manually. The Harper cluster -# fetches the tagged commit over SSH (pinned by its exact SHA, so peers can't diverge on a moved tag) -# using the read-only deploy key you registered once with `npm run deploy:setup`. +# fetches the tagged commit over git+https (pinned by its exact SHA, so peers can't diverge on a +# moved tag), authenticating a private clone with the encrypted token you sealed once via +# `npm run deploy:setup`. The credential lives on the cluster, so this workflow handles no token. # # Required repository secrets (Settings → Secrets and variables → Actions): # CLI_TARGET your cluster's operations URL, e.g. https://my-cluster.harperdb.io:9925 # HARPER_CLI_USERNAME a cluster user allowed to deploy # HARPER_CLI_PASSWORD that user's password # -# Public repo and want zero cluster-side auth, or prefer building in CI and publishing to a registry? -# See the "Deployment" section of the README for those alternatives. +# Public repo? Drop `credential=github.com` from the `deploy` script — no cluster-side auth needed. +# See the "Deployment" section of the README for details. name: Deploy to Harper Fabric on: workflow_dispatch: