create-harper 1.12.12 → 1.13.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/README.md +18 -6
  2. package/lib/constants/helpMessage.js +3 -0
  3. package/lib/fs/copyFile.js +31 -15
  4. package/lib/pkg/toComponentName.js +20 -0
  5. package/lib/steps/installAndOptionallyStart.js +15 -0
  6. package/lib/steps/scaffoldProject.js +4 -0
  7. package/package.json +2 -2
  8. package/template-nextjs/README.md +65 -17
  9. package/template-nextjs/_github/workflows/deploy.yaml +99 -41
  10. package/template-nextjs/package.json +2 -1
  11. package/template-nextjs-ts/README.md +65 -17
  12. package/template-nextjs-ts/_github/workflows/deploy.yaml +99 -41
  13. package/template-nextjs-ts/package.json +2 -1
  14. package/template-react/README.md +57 -25
  15. package/template-react/_github/workflows/deploy.yaml +90 -39
  16. package/template-react/package.json +2 -2
  17. package/template-react-ssr/README.md +57 -25
  18. package/template-react-ssr/_github/workflows/deploy.yaml +90 -39
  19. package/template-react-ssr/package.json +2 -2
  20. package/template-react-ts/README.md +57 -25
  21. package/template-react-ts/_github/workflows/deploy.yaml +90 -39
  22. package/template-react-ts/package.json +2 -2
  23. package/template-react-ts-ssr/README.md +57 -25
  24. package/template-react-ts-ssr/_github/workflows/deploy.yaml +90 -39
  25. package/template-react-ts-ssr/package.json +2 -2
  26. package/template-vanilla/README.md +57 -25
  27. package/template-vanilla/_github/workflows/deploy.yaml +90 -39
  28. package/template-vanilla/package.json +5 -3
  29. package/template-vanilla-ts/README.md +57 -25
  30. package/template-vanilla-ts/_github/workflows/deploy.yaml +90 -39
  31. package/template-vanilla-ts/package.json +5 -3
  32. package/template-vue/README.md +57 -25
  33. package/template-vue/_github/workflows/deploy.yaml +90 -39
  34. package/template-vue/package.json +2 -2
  35. package/template-vue-ssr/README.md +57 -25
  36. package/template-vue-ssr/_github/workflows/deploy.yaml +90 -39
  37. package/template-vue-ssr/package.json +2 -2
  38. package/template-vue-ts/README.md +57 -25
  39. package/template-vue-ts/_github/workflows/deploy.yaml +90 -39
  40. package/template-vue-ts/package.json +2 -2
  41. package/template-vue-ts-ssr/README.md +57 -25
  42. package/template-vue-ts-ssr/_github/workflows/deploy.yaml +90 -39
  43. package/template-vue-ts-ssr/package.json +2 -2
package/README.md CHANGED
@@ -65,15 +65,27 @@ deno init --npm harper my-react-app --template react-ts
65
65
 
66
66
  Currently supported template presets include:
67
67
 
68
- - `vanilla`
69
- - `vanilla-ts`
70
- - `react`
71
- - `react-ts`
72
- - `nextjs`
73
- - `nextjs-ts`
68
+ - `vanilla`, `vanilla-ts`
69
+ - `react`, `react-ts`, `react-ssr`, `react-ts-ssr`
70
+ - `vue`, `vue-ts`, `vue-ssr`, `vue-ts-ssr`
71
+ - `nextjs`, `nextjs-ts`
74
72
 
75
73
  You can use `.` for the project name to scaffold in the current directory.
76
74
 
75
+ ## Deployment
76
+
77
+ Every project comes with a GitHub Actions workflow that tests pull requests and deploys to your [Harper Fabric](https://fabric.harper.fast/) cluster when a change merges to `main`. It stores no Harper credential: the deploy job authenticates with GitHub's OIDC identity token, which the cluster accepts under a trust policy.
78
+
79
+ After you push the new project to GitHub, set that up once from the project, signed in to the cluster as a super user with `harper login` (Harper 5.4 or later):
80
+
81
+ ```bash
82
+ npm run deploy:setup-ci
83
+ ```
84
+
85
+ It creates a deploy-only user and the trust policy on the cluster, and sets the workflow's `HARPER_CLI_TARGET` repository variable. Each project's README covers the rest: going back to an earlier release, staging a release, and what to do when a run is refused.
86
+
87
+ Projects created before this deploy on version tags with a stored `HARPER_CLI_REFRESH_TOKEN`. To move one over, scaffold a new project with the same name, template and package manager, copy its `.github/workflows/deploy.yaml` over yours, run `harper deploy setup=true provider=github-actions project=<the workflow's project= value>`, push, and then delete the old secret.
88
+
77
89
  ## Auto-updates
78
90
 
79
91
  `create-harper` will automatically check for newer versions on npm. If a newer version is available, it will automatically re-run the process using the latest version to ensure you are using the most up-to-date templates and features.
@@ -38,5 +38,8 @@ If you are going to deploy your application to https://fabric.harper.fast/, you
38
38
  -c, --deploymentURL The https://fabric.harper.fast/ URL where you will host your application
39
39
  For authentication, use "harper login" in your project directory.
40
40
 
41
+ Projects deploy from GitHub Actions when a change merges to main. After pushing the project to GitHub, run
42
+ its "deploy:setup-ci" script once to let the workflow deploy to your cluster (see the project's README).
43
+
41
44
  Available templates:
42
45
  ${availableTemplates}`;
@@ -14,22 +14,34 @@ const DEFAULT_TARGETS = new Set([defaultTarget, 'your-fabric.harper.fast-cluster
14
14
  const TARGET_ASSIGNMENT = /^[ \t]*(?:export[ \t]+)?(?:HARPER_CLI_TARGET|CLI_TARGET)[ \t]*=/;
15
15
 
16
16
  /**
17
- * @param {string} existingEnv - The existing `.env` content.
17
+ * @param {string} line - One line of the template's `.env` content.
18
+ * @returns {boolean} Whether the line sets the target to a placeholder.
19
+ */
20
+ function setsPlaceholderTarget(line) {
21
+ return TARGET_ASSIGNMENT.test(line) && Object.values(dotenv.parse(line)).some((value) => DEFAULT_TARGETS.has(value));
22
+ }
23
+
24
+ /**
25
+ * The CLI reads a target from `.env` ahead of the one `harper login` saves, so a placeholder there
26
+ * would send every command to a host that doesn't exist. With no cluster URL supplied, the target
27
+ * line is written commented out instead, and `harper login` adds the real one; when the existing
28
+ * `.env` already sets a target, the line is left out.
29
+ *
18
30
  * @param {string} templateEnv - The template's `.env` content, after substitution.
19
- * @returns {string} The template content to append. The last assignment wins, so a default
20
- * target appended after a configured one would replace it.
31
+ * @param {string} [existingEnv] - The existing `.env` content, when the template is appended to it.
32
+ * @returns {string} The template content to write.
21
33
  */
22
- function harperEnvToAppend(existingEnv, templateEnv) {
34
+ function withoutPlaceholderTarget(templateEnv, existingEnv = '') {
23
35
  const existing = dotenv.parse(existingEnv);
24
- const template = dotenv.parse(templateEnv);
25
- const keepsConfiguredTarget = TARGET_KEYS.some((key) => existing[key])
26
- && TARGET_KEYS.some((key) => DEFAULT_TARGETS.has(template[key]));
27
- if (!keepsConfiguredTarget) {
28
- return templateEnv;
29
- }
36
+ const hasTarget = TARGET_KEYS.some((key) => existing[key]);
30
37
  return templateEnv
31
38
  .split('\n')
32
- .filter((line) => !TARGET_ASSIGNMENT.test(line))
39
+ .flatMap((line) => {
40
+ if (!setsPlaceholderTarget(line)) {
41
+ return [line];
42
+ }
43
+ return hasTarget ? [] : [`# ${line.trim()}`];
44
+ })
33
45
  .join('\n');
34
46
  }
35
47
 
@@ -42,13 +54,17 @@ function harperEnvToAppend(existingEnv, templateEnv) {
42
54
  */
43
55
  export function copyFile(sourcePath, targetPath, substitutions) {
44
56
  let updatedContent = applySubstitutions(fs.readFileSync(sourcePath, 'utf-8'), targetPath, substitutions);
45
- if (targetPath.endsWith('.env') && fs.existsSync(targetPath)) {
46
- const existingContent = fs.readFileSync(targetPath, 'utf-8');
47
- updatedContent = `# Your .env file contents:
57
+ if (targetPath.endsWith('.env')) {
58
+ if (fs.existsSync(targetPath)) {
59
+ const existingContent = fs.readFileSync(targetPath, 'utf-8');
60
+ updatedContent = `# Your .env file contents:
48
61
  ${existingContent}
49
62
 
50
63
  # Harper .env contents:
51
- ${harperEnvToAppend(existingContent, updatedContent)}`;
64
+ ${withoutPlaceholderTarget(updatedContent, existingContent)}`;
65
+ } else {
66
+ updatedContent = withoutPlaceholderTarget(updatedContent);
67
+ }
52
68
  }
53
69
  writeFile(targetPath, updatedContent);
54
70
 
@@ -0,0 +1,20 @@
1
+ /**
2
+ * The name a project deploys under. Harper accepts only letters, numbers, dashes and underscores in a
3
+ * component name, and the name is substituted into shell commands in the scaffolded package scripts
4
+ * and workflow, so a project directory named `my app` or `a; b` must not reach them as typed.
5
+ *
6
+ * @param {string} projectName - The name of the directory the project lives in.
7
+ * @returns {string} - A component name made of `[A-Za-z0-9_-]`.
8
+ */
9
+ export function toComponentName(projectName) {
10
+ const name = String(projectName ?? '').replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '');
11
+ if (!name) { return 'app'; }
12
+ // The harper CLI JSON-parses each `key=value` argument, so `2026` or `true` would arrive as a number
13
+ // or a boolean rather than a name.
14
+ try {
15
+ JSON.parse(name);
16
+ return `app-${name}`;
17
+ } catch {
18
+ return name;
19
+ }
20
+ }
@@ -1,4 +1,5 @@
1
1
  import * as prompts from '@clack/prompts';
2
+ import fs from 'node:fs';
2
3
  import path from 'node:path';
3
4
  import { install } from '../install.js';
4
5
  import { getInstallCommand } from '../pkg/getInstallCommand.js';
@@ -20,6 +21,20 @@ export function installAndOptionallyStart(root, pkgManager, immediate, skipInsta
20
21
  install(root, pkgManager, selectedSkills, selectedAgents);
21
22
  }
22
23
 
24
+ // The scaffolder can't do this setup itself: the GitHub repository rarely exists yet.
25
+ if (fs.existsSync(path.join(root, '.github', 'workflows', 'deploy.yaml'))) {
26
+ prompts.note(
27
+ [
28
+ '1. Push this project to a GitHub repository.',
29
+ '2. Sign in to your cluster as a super user: harper login',
30
+ `3. ${getRunCommand(pkgManager, 'deploy:setup-ci').join(' ')}`,
31
+ '',
32
+ 'Then merging to main deploys. See "Deployment" in README.md.',
33
+ ].join('\n'),
34
+ 'Deploy from GitHub',
35
+ );
36
+ }
37
+
23
38
  if (immediate && !skipInstall) {
24
39
  start(root, pkgManager);
25
40
  } else {
@@ -4,6 +4,7 @@ import path from 'node:path';
4
4
  import { fileURLToPath } from 'node:url';
5
5
  import { crawlTemplateDir } from '../fs/crawlTemplateDir.js';
6
6
  import { getWorkflowSubstitutions } from '../pkg/getWorkflowSubstitutions.js';
7
+ import { toComponentName } from '../pkg/toComponentName.js';
7
8
 
8
9
  /**
9
10
  * Step 6: Create the project structure and files based on the collected information.
@@ -23,6 +24,9 @@ export function scaffoldProject(root, projectName, packageName, template, envVar
23
24
  const agent = pkgManager || 'npm';
24
25
  const substitutions = {
25
26
  'your-project-name-here': projectName || 'your-project-name-here',
27
+ // From the directory the app lives in, as `harper deploy` derives a project name; the project
28
+ // name argument can be `.` or a path.
29
+ 'your-component-name-here': toComponentName(path.basename(root)),
26
30
  'your-package-name-here': packageName || 'your-package-name-here',
27
31
  'your-fabric.harper.fast-cluster-url-here': envVars?.target || 'your-fabric.harper.fast-cluster-url-here',
28
32
  // Substitution runs these keys in order as plain string replaces, so the longer
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "create-harper",
3
3
  "description": "Scaffold a new Harper project in JavaScript or TypeScript.",
4
- "version": "1.12.12",
4
+ "version": "1.13.1",
5
5
  "type": "module",
6
6
  "sideEffects": false,
7
7
  "exports": {
@@ -80,7 +80,7 @@
80
80
  "conventional-changelog-conventionalcommits": "^9.3.1",
81
81
  "conventional-commits-filter": "^6.0.1",
82
82
  "conventional-commits-parser": "^7.1.0",
83
- "dprint": "^0.61.0",
83
+ "dprint": "^0.63.0",
84
84
  "oxlint": "^1.38.0",
85
85
  "semantic-release": "^25.0.2",
86
86
  "vitest": "^5.0.0"
@@ -56,45 +56,93 @@ Put data access in **server actions** (see [`app/actions.js`](./app/actions.js))
56
56
 
57
57
  ## Deployment
58
58
 
59
- When you are ready, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in to your account, and create a cluster.
59
+ Your app deploys from GitHub: every pull request runs lint, and merging to `main` deploys to your Harper cluster with the included [GitHub Actions workflow](./.github/workflows/deploy.yaml). No Harper password or token is stored in GitHub.
60
60
 
61
- Come back and log your local CLI into your cluster:
61
+ 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 as a super user:
62
62
 
63
63
  ```sh
64
64
  harper login
65
65
  ```
66
66
 
67
- Then deploy your app:
67
+ ### How the workflow authenticates
68
+
69
+ The workflow runs plain `harper` commands, such as `harper deploy`, with no credentials on them. Each one authenticates by itself, because:
70
+
71
+ - the deploy job has `permissions: id-token: write`, so the CLI can ask GitHub for an identity token for the run;
72
+ - `HARPER_CLI_TARGET` is set to your cluster's URL, so the CLI asks for a token addressed to that cluster;
73
+ - the cluster holds a **trust policy** that accepts tokens from this repository's `deploy.yaml`, on `main`, in the `production` environment, and lets them act as a deploy-only user.
74
+
75
+ The CLI trades the token for a one-hour Harper token, and the run prints which policy it used, like `Authenticated as 'my-app-ci-deploy' via OIDC trust policy 'github-actions-my-app'`. Every `harper` command in that job works the same way, so you can add more steps without adding credentials.
76
+
77
+ ### One-time setup
78
+
79
+ Push the project to a GitHub repository, then run this from the project on your machine. It needs Harper 5.4 or later (`npm install --global harper`):
68
80
 
69
81
  ```sh
70
- your-package-manager-run-here deploy
82
+ your-package-manager-run-here deploy:setup-ci
71
83
  ```
72
84
 
73
- `your-package-manager-run-here deploy` runs `next build` locally and ships the prebuilt `.next` output, then Harper serves it — no build runs on the cluster. (Building on the cluster currently fails; see the note in [`config.yaml`](./config.yaml).)
85
+ It creates, on the cluster:
86
+
87
+ - a role that can run only `deploy_component`, `get_job` (to wait for the rollout) and `registration_info` (the CLI's version check), and a user in it;
88
+ - the trust policy, checked against your `.github/workflows/deploy.yaml` so it matches what a run will present.
89
+
90
+ With the [`gh` CLI](https://cli.github.com) signed in, it also sets the `HARPER_CLI_TARGET` repository variable; otherwise it prints the command to run. Running it again changes nothing. If something on the cluster already exists and differs, it stops and says what, without changing anything.
91
+
92
+ Then merge to `main`, or run the workflow from the **Actions** tab, to deploy.
93
+
94
+ The deploy user can deploy any app on the cluster, so who can deploy comes down to who can merge to `main`. Protect `main` under **Settings → Branches**, and if you want a person to approve each release, add a required reviewer to the `production` environment under **Settings → Environments**.
95
+
96
+ ### What a deploy does
97
+
98
+ The workflow runs `next build` and uploads the project with its `.next` build, so no build runs on the cluster (building there currently fails; see the note in [`config.yaml`](./config.yaml)). It deploys with `restart=rolling`: each node restarts in turn, so the cluster keeps serving. On Harper 5.4 and later, each node first loads the release in a canary worker, and only serves it if it loads. A release that fails to load is rejected, the run fails and names the node, and the previous release keeps serving.
99
+
100
+ The run's summary names the deployment and its `certification`:
74
101
 
75
- ### Deploy automatically from CI
102
+ - `certified`: the canary loaded the release.
103
+ - `uncertified` or `unavailable`: the release went out without that check, for a reason the [deploy reference](https://docs.harperdb.io/reference/v5/operations-api/operations#certifying-a-release-in-a-canary-worker) lists.
76
104
 
77
- The included [GitHub Actions workflow](./.github/workflows/deploy.yaml) builds and deploys whenever you push a version tag:
105
+ ### Going back to an earlier release
106
+
107
+ Each node keeps the releases a deploy replaces. List them, then activate one by putting its `deployment_id` in place of `DEPLOYMENT_ID`; nothing is reinstalled:
78
108
 
79
109
  ```sh
80
- git tag v1.0.0
81
- git push --tags
110
+ harper list_deployments project=your-component-name-here
111
+ harper deploy project=your-component-name-here deployment_id=DEPLOYMENT_ID restart=rolling
82
112
  ```
83
113
 
84
- Add these repository secrets first, under **Settings → Secrets and variables → Actions**:
85
-
86
- - `HARPER_CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`)
87
- - `HARPER_CLI_REFRESH_TOKEN` — a long-lived token CI authenticates with, so no password is stored
114
+ To have a person decide when a release goes live, deploy with `activate=false` instead: it installs the release without serving it, and prints a `deployment_id` you activate later with the second command above.
88
115
 
89
- Set both in one command — this pipes the credentials straight from your cluster into GitHub, so the token never appears on screen or in your shell history:
116
+ ### Deploying by hand
90
117
 
91
118
  ```sh
92
- harper login --for-ci | gh secret set --env-file -
119
+ your-package-manager-run-here deploy
93
120
  ```
94
121
 
95
- (No [`gh` CLI](https://cli.github.com)? `harper login --for-ci | pbcopy` copies the two lines for you to paste in by hand.)
122
+ builds and deploys this directory the same way, as the user you logged in with. It returns once the first node has the release; the response's `restartJobId` is the job that takes it to the others, which `harper get_job id=<restartJobId>` reports on.
123
+
124
+ ### When a run is refused
125
+
126
+ If the deploy step fails with a 401, the cluster did not accept the run's token. `harper list_oidc_trust` shows each policy, and an `invalid_reason` when one can't match; the cluster's `oidc-trust` log says which check failed. Rerunning `your-package-manager-run-here deploy:setup-ci` reports a policy that no longer matches the workflow.
127
+
128
+ ### Moving from the earlier workflow
129
+
130
+ Projects created before this deployed on version tags with a `HARPER_CLI_REFRESH_TOKEN` secret, and don't have this workflow or the `deploy:setup-ci` script. To move one over:
131
+
132
+ 1. Scaffold a new project with the same name and template, using the package manager your project uses (for example `pnpm create harper`), and copy its `.github/workflows/deploy.yaml` over yours.
133
+ 2. Run the setup from the project, with the `project=` value the copied workflow passes to `harper deploy`: `harper deploy setup=true provider=github-actions project=<that value>`.
134
+ 3. Push the new workflow to `main`.
135
+ 4. Once nothing references it, delete the `HARPER_CLI_REFRESH_TOKEN` secret under **Settings → Secrets and variables → Actions**. The new workflow doesn't read it, so it is only a credential left lying around.
136
+
137
+ ### Private npm dependencies
138
+
139
+ The cluster installs your dependencies itself. If any come from a private npm registry, give the cluster a read-only token for it once. It is encrypted on your machine, and only the ciphertext is stored:
140
+
141
+ ```sh
142
+ harper deploy setup=true provider=npm project=your-component-name-here registry=https://npm.pkg.github.com scope=@your-org
143
+ ```
96
144
 
97
- > **Why this template deploys differently.** The other create-harper templates deploy _by reference_: the cluster clones your repo at a pinned commit and builds there. Next.js can't do that yet — `.next` is gitignored, so a git reference carries no build output, and an on-cluster build currently fails ([nextjs#57](https://github.com/HarperFast/nextjs/issues/57), [nextjs#58](https://github.com/HarperFast/nextjs/issues/58)). Until those land, this template uploads the build itself.
145
+ Leave out `registry=` and `scope=` for a private package on npmjs.com.
98
146
 
99
147
  ## Keep Going!
100
148
 
@@ -1,48 +1,36 @@
1
- # Deploys this app to your Harper cluster by *payload* via `harper deploy_component .`
2
- # (`your-package-manager-run-here deploy`), which runs `next build` first and uploads the prebuilt
3
- # `.next` output.
4
- #
5
- # The other create-harper templates deploy by *reference* (`harper deploy by_ref=true`), where the
6
- # cluster clones your repo and builds on the node. Next.js can't use that yet: `.next` is gitignored
7
- # (so a git reference carries no build output) and building on the cluster currently fails —
8
- # Turbopack crashes inside a Harper worker thread (HarperFast/nextjs#57) and a webpack build
9
- # overruns the component-load timeout (HarperFast/nextjs#58). Once those land, this template can
10
- # switch to the by-reference workflow like the rest.
11
- #
12
- # Runs on a version tag (e.g. `git tag v1.2.3 && git push --tags`) or manually.
13
- #
14
- # Required repository secrets (Settings → Secrets and variables → Actions):
15
- # HARPER_CLI_TARGET your cluster's operations URL, e.g. https://my-cluster.harperdb.io:9925
16
- # HARPER_CLI_REFRESH_TOKEN a long-lived refresh token; the CLI mints a short-lived operation
17
- # token from it on each run, so no password is stored in CI
18
- #
19
- # Set both in one command — this pipes them straight from your cluster into GitHub, so the token
20
- # never appears on screen or in your shell history:
21
- #
22
- # harper login --for-ci | gh secret set --env-file -
23
- name: Deploy to Harper Fabric
1
+ # Tests every pull request, and deploys to your Harper cluster when a change merges to `main`. The
2
+ # deploy job holds no Harper credential: its `harper` commands authenticate with GitHub's OIDC token
3
+ # under a trust policy on the cluster. Set that up once with
4
+ # `your-package-manager-run-here deploy:setup-ci` (see "Deployment" in the README). The deploy job
5
+ # runs `next build` and uploads it, because building on the cluster currently fails
6
+ # (HarperFast/nextjs#57, HarperFast/nextjs#58).
7
+ name: Deploy to Harper
24
8
  on:
25
- workflow_dispatch:
9
+ pull_request:
26
10
  push:
27
- tags:
28
- - 'v*'
11
+ branches: [main]
12
+ workflow_dispatch:
13
+
14
+ permissions:
15
+ contents: read
29
16
 
17
+ # One run per branch at a time, so an older commit can't deploy after a newer one; a newer run
18
+ # replaces one still waiting. On a pull request, a new push cancels the run in progress.
30
19
  concurrency:
31
- group: deploy
32
- cancel-in-progress: false
20
+ group: deploy-${{ github.ref }}
21
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
33
22
 
34
23
  jobs:
35
- deploy:
24
+ test:
36
25
  runs-on: ubuntu-latest
37
26
  steps:
38
27
  - name: Checkout code
39
- uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
28
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
40
29
  with:
41
- fetch-depth: 0
42
- fetch-tags: true
30
+ persist-credentials: false
43
31
  # your-package-manager-setup-step-here
44
32
  - name: Set up Node.js
45
- uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
33
+ uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
46
34
  with:
47
35
  # your-package-manager-node-cache-here
48
36
  node-version-file: '.nvmrc'
@@ -50,13 +38,83 @@ jobs:
50
38
  run: your-package-manager-install-here
51
39
  - name: Run lint
52
40
  run: your-package-manager-run-here lint
41
+
42
+ deploy:
43
+ needs: test
44
+ if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
45
+ runs-on: ubuntu-latest
46
+ environment: production
47
+ permissions:
48
+ contents: read
49
+ id-token: write
50
+ env:
51
+ HARPER_CLI_TARGET: ${{ vars.HARPER_CLI_TARGET }}
52
+ steps:
53
+ - name: Refuse to redeploy an older commit
54
+ # Re-running an old run keeps its commit, which would replace a newer release.
55
+ if: github.run_attempt > 1
56
+ env:
57
+ GH_TOKEN: ${{ github.token }}
58
+ run: |
59
+ HEAD=$(gh api "repos/$GITHUB_REPOSITORY/commits/$GITHUB_REF_NAME" --jq .sha)
60
+ [ "$HEAD" = "$GITHUB_SHA" ] || { echo "::error::$GITHUB_REF_NAME is now at $HEAD; re-running this deploy would replace it with $GITHUB_SHA"; exit 1; }
61
+ - name: Checkout code
62
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
63
+ with:
64
+ # The deploy uploads this directory, `.git` included, so keep the job's token out of it.
65
+ persist-credentials: false
66
+ # your-package-manager-setup-step-here
67
+ - name: Set up Node.js
68
+ uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
69
+ with:
70
+ # your-package-manager-node-cache-here
71
+ node-version-file: '.nvmrc'
72
+ - name: Install dependencies
73
+ run: your-package-manager-install-here
74
+ - name: Build
75
+ run: your-package-manager-run-here build
53
76
  - name: Install Harper CLI
54
- # Installed with npm regardless of this project's package manager: it is a global tool, and
55
- # npm always comes with the Node.js set up above. Pinned to the 5.2 line; ^5.2.0 blocks a
56
- # breaking 6.x bump.
57
- run: npm install -g harper@^5.2.0
58
- - name: Build & deploy
59
- run: your-package-manager-run-here deploy
77
+ # 5.3 is the first CLI that authenticates with the OIDC token.
78
+ run: npm install --global harper@^5.3
79
+ - name: Deploy
80
+ run: |
81
+ # With no target the CLI would fall back to a saved login or a local node, and succeed.
82
+ [ -n "$HARPER_CLI_TARGET" ] || { echo "::error::Set the HARPER_CLI_TARGET repository variable: run your-package-manager-run-here deploy:setup-ci"; exit 1; }
83
+ harper deploy project=your-component-name-here restart=rolling json=true > "$RUNNER_TEMP/deploy.json"
84
+ - name: Wait for every node to take the release
85
+ # The deploy returns once the node it reached has the release; the others take it in a job.
86
+ run: |
87
+ JOB_ID=$(jq -r '.restartJobId // empty' "$RUNNER_TEMP/deploy.json")
88
+ [ -n "$JOB_ID" ] || { echo "::error::The rolling deploy returned no restartJobId"; exit 1; }
89
+ LAST="could not be read"
90
+ for attempt in $(seq 60); do
91
+ sleep 10
92
+ harper get_job id="$JOB_ID" json=true > "$RUNNER_TEMP/job.json" || continue
93
+ case $(jq -r '.[0].status // "MISSING"' "$RUNNER_TEMP/job.json") in
94
+ COMPLETE) exit 0 ;;
95
+ ERROR) jq -r '.[0].message' "$RUNNER_TEMP/job.json"; exit 1 ;;
96
+ MISSING) LAST="was not on the node that answered; its outcome is unknown" ;;
97
+ *) LAST="was still running" ;;
98
+ esac
99
+ done
100
+ echo "::error::After 60 polls, job $JOB_ID $LAST"
101
+ exit 1
102
+ - name: Summarize
103
+ if: ${{ !cancelled() }}
60
104
  env:
61
- HARPER_CLI_TARGET: ${{ secrets.HARPER_CLI_TARGET }}
62
- HARPER_CLI_REFRESH_TOKEN: ${{ secrets.HARPER_CLI_REFRESH_TOKEN }}
105
+ JOB_STATUS: ${{ job.status }}
106
+ run: |
107
+ [ -s "$RUNNER_TEMP/deploy.json" ] || exit 0
108
+ {
109
+ if [ "$JOB_STATUS" = success ]; then
110
+ echo "### Deployed your-component-name-here"
111
+ elif jq -e '.deployment_id' "$RUNNER_TEMP/deploy.json" > /dev/null; then
112
+ echo "### Deploy of your-component-name-here did not complete on every node"
113
+ else
114
+ echo "### Deploy of your-component-name-here failed"
115
+ fi
116
+ jq -r '"- Deployment: `\(.deployment_id // "unknown")`\n- Certification: `\(.certification // "not reported")`"' "$RUNNER_TEMP/deploy.json"
117
+ echo ""
118
+ echo "To go back to an earlier release, list them with \`harper list_deployments project=your-component-name-here\`,"
119
+ echo "then activate one with \`harper deploy project=your-component-name-here deployment_id=DEPLOYMENT_ID restart=rolling\`."
120
+ } >> "$GITHUB_STEP_SUMMARY"
@@ -11,7 +11,8 @@
11
11
  "build": "next build",
12
12
  "lint": "eslint .",
13
13
  "format": "prettier --write .",
14
- "deploy": "next build && harper deploy_component . restart=true replicated=true"
14
+ "deploy": "next build && harper deploy project=your-component-name-here restart=rolling",
15
+ "deploy:setup-ci": "harper deploy setup=true provider=github-actions project=your-component-name-here"
15
16
  },
16
17
  "dependencies": {
17
18
  "@harperfast/nextjs": "^2.2.3",
@@ -56,45 +56,93 @@ Put data access in **server actions** (see [`app/actions.ts`](./app/actions.ts))
56
56
 
57
57
  ## Deployment
58
58
 
59
- When you are ready, head to [https://fabric.harper.fast/](https://fabric.harper.fast/), log in to your account, and create a cluster.
59
+ Your app deploys from GitHub: every pull request runs lint, and merging to `main` deploys to your Harper cluster with the included [GitHub Actions workflow](./.github/workflows/deploy.yaml). No Harper password or token is stored in GitHub.
60
60
 
61
- Come back and log your local CLI into your cluster:
61
+ 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 as a super user:
62
62
 
63
63
  ```sh
64
64
  harper login
65
65
  ```
66
66
 
67
- Then deploy your app:
67
+ ### How the workflow authenticates
68
+
69
+ The workflow runs plain `harper` commands, such as `harper deploy`, with no credentials on them. Each one authenticates by itself, because:
70
+
71
+ - the deploy job has `permissions: id-token: write`, so the CLI can ask GitHub for an identity token for the run;
72
+ - `HARPER_CLI_TARGET` is set to your cluster's URL, so the CLI asks for a token addressed to that cluster;
73
+ - the cluster holds a **trust policy** that accepts tokens from this repository's `deploy.yaml`, on `main`, in the `production` environment, and lets them act as a deploy-only user.
74
+
75
+ The CLI trades the token for a one-hour Harper token, and the run prints which policy it used, like `Authenticated as 'my-app-ci-deploy' via OIDC trust policy 'github-actions-my-app'`. Every `harper` command in that job works the same way, so you can add more steps without adding credentials.
76
+
77
+ ### One-time setup
78
+
79
+ Push the project to a GitHub repository, then run this from the project on your machine. It needs Harper 5.4 or later (`npm install --global harper`):
68
80
 
69
81
  ```sh
70
- your-package-manager-run-here deploy
82
+ your-package-manager-run-here deploy:setup-ci
71
83
  ```
72
84
 
73
- `your-package-manager-run-here deploy` runs `next build` locally and ships the prebuilt `.next` output, then Harper serves it — no build runs on the cluster. (Building on the cluster currently fails; see the note in [`config.yaml`](./config.yaml).)
85
+ It creates, on the cluster:
86
+
87
+ - a role that can run only `deploy_component`, `get_job` (to wait for the rollout) and `registration_info` (the CLI's version check), and a user in it;
88
+ - the trust policy, checked against your `.github/workflows/deploy.yaml` so it matches what a run will present.
89
+
90
+ With the [`gh` CLI](https://cli.github.com) signed in, it also sets the `HARPER_CLI_TARGET` repository variable; otherwise it prints the command to run. Running it again changes nothing. If something on the cluster already exists and differs, it stops and says what, without changing anything.
91
+
92
+ Then merge to `main`, or run the workflow from the **Actions** tab, to deploy.
93
+
94
+ The deploy user can deploy any app on the cluster, so who can deploy comes down to who can merge to `main`. Protect `main` under **Settings → Branches**, and if you want a person to approve each release, add a required reviewer to the `production` environment under **Settings → Environments**.
95
+
96
+ ### What a deploy does
97
+
98
+ The workflow runs `next build` and uploads the project with its `.next` build, so no build runs on the cluster (building there currently fails; see the note in [`config.yaml`](./config.yaml)). It deploys with `restart=rolling`: each node restarts in turn, so the cluster keeps serving. On Harper 5.4 and later, each node first loads the release in a canary worker, and only serves it if it loads. A release that fails to load is rejected, the run fails and names the node, and the previous release keeps serving.
99
+
100
+ The run's summary names the deployment and its `certification`:
74
101
 
75
- ### Deploy automatically from CI
102
+ - `certified`: the canary loaded the release.
103
+ - `uncertified` or `unavailable`: the release went out without that check, for a reason the [deploy reference](https://docs.harperdb.io/reference/v5/operations-api/operations#certifying-a-release-in-a-canary-worker) lists.
76
104
 
77
- The included [GitHub Actions workflow](./.github/workflows/deploy.yaml) builds and deploys whenever you push a version tag:
105
+ ### Going back to an earlier release
106
+
107
+ Each node keeps the releases a deploy replaces. List them, then activate one by putting its `deployment_id` in place of `DEPLOYMENT_ID`; nothing is reinstalled:
78
108
 
79
109
  ```sh
80
- git tag v1.0.0
81
- git push --tags
110
+ harper list_deployments project=your-component-name-here
111
+ harper deploy project=your-component-name-here deployment_id=DEPLOYMENT_ID restart=rolling
82
112
  ```
83
113
 
84
- Add these repository secrets first, under **Settings → Secrets and variables → Actions**:
85
-
86
- - `HARPER_CLI_TARGET` — your cluster's operations URL (e.g. `https://your-cluster.harperdb.io:9925`)
87
- - `HARPER_CLI_REFRESH_TOKEN` — a long-lived token CI authenticates with, so no password is stored
114
+ To have a person decide when a release goes live, deploy with `activate=false` instead: it installs the release without serving it, and prints a `deployment_id` you activate later with the second command above.
88
115
 
89
- Set both in one command — this pipes the credentials straight from your cluster into GitHub, so the token never appears on screen or in your shell history:
116
+ ### Deploying by hand
90
117
 
91
118
  ```sh
92
- harper login --for-ci | gh secret set --env-file -
119
+ your-package-manager-run-here deploy
93
120
  ```
94
121
 
95
- (No [`gh` CLI](https://cli.github.com)? `harper login --for-ci | pbcopy` copies the two lines for you to paste in by hand.)
122
+ builds and deploys this directory the same way, as the user you logged in with. It returns once the first node has the release; the response's `restartJobId` is the job that takes it to the others, which `harper get_job id=<restartJobId>` reports on.
123
+
124
+ ### When a run is refused
125
+
126
+ If the deploy step fails with a 401, the cluster did not accept the run's token. `harper list_oidc_trust` shows each policy, and an `invalid_reason` when one can't match; the cluster's `oidc-trust` log says which check failed. Rerunning `your-package-manager-run-here deploy:setup-ci` reports a policy that no longer matches the workflow.
127
+
128
+ ### Moving from the earlier workflow
129
+
130
+ Projects created before this deployed on version tags with a `HARPER_CLI_REFRESH_TOKEN` secret, and don't have this workflow or the `deploy:setup-ci` script. To move one over:
131
+
132
+ 1. Scaffold a new project with the same name and template, using the package manager your project uses (for example `pnpm create harper`), and copy its `.github/workflows/deploy.yaml` over yours.
133
+ 2. Run the setup from the project, with the `project=` value the copied workflow passes to `harper deploy`: `harper deploy setup=true provider=github-actions project=<that value>`.
134
+ 3. Push the new workflow to `main`.
135
+ 4. Once nothing references it, delete the `HARPER_CLI_REFRESH_TOKEN` secret under **Settings → Secrets and variables → Actions**. The new workflow doesn't read it, so it is only a credential left lying around.
136
+
137
+ ### Private npm dependencies
138
+
139
+ The cluster installs your dependencies itself. If any come from a private npm registry, give the cluster a read-only token for it once. It is encrypted on your machine, and only the ciphertext is stored:
140
+
141
+ ```sh
142
+ harper deploy setup=true provider=npm project=your-component-name-here registry=https://npm.pkg.github.com scope=@your-org
143
+ ```
96
144
 
97
- > **Why this template deploys differently.** The other create-harper templates deploy _by reference_: the cluster clones your repo at a pinned commit and builds there. Next.js can't do that yet — `.next` is gitignored, so a git reference carries no build output, and an on-cluster build currently fails ([nextjs#57](https://github.com/HarperFast/nextjs/issues/57), [nextjs#58](https://github.com/HarperFast/nextjs/issues/58)). Until those land, this template uploads the build itself.
145
+ Leave out `registry=` and `scope=` for a private package on npmjs.com.
98
146
 
99
147
  ## Keep Going!
100
148