create-harper 1.12.11 → 1.13.0
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.
- package/README.md +18 -6
- package/lib/constants/helpMessage.js +3 -0
- package/lib/fs/copyFile.js +31 -15
- package/lib/pkg/toComponentName.js +20 -0
- package/lib/steps/installAndOptionallyStart.js +15 -0
- package/lib/steps/scaffoldProject.js +4 -0
- package/package.json +2 -2
- package/template-nextjs/README.md +65 -17
- package/template-nextjs/_github/workflows/deploy.yaml +99 -41
- package/template-nextjs/package.json +2 -1
- package/template-nextjs-ts/README.md +65 -17
- package/template-nextjs-ts/_github/workflows/deploy.yaml +99 -41
- package/template-nextjs-ts/package.json +2 -1
- package/template-react/README.md +57 -25
- package/template-react/_github/workflows/deploy.yaml +90 -39
- package/template-react/package.json +2 -2
- package/template-react-ssr/README.md +57 -25
- package/template-react-ssr/_github/workflows/deploy.yaml +90 -39
- package/template-react-ssr/package.json +2 -2
- package/template-react-ts/README.md +57 -25
- package/template-react-ts/_github/workflows/deploy.yaml +90 -39
- package/template-react-ts/package.json +2 -2
- package/template-react-ts-ssr/README.md +57 -25
- package/template-react-ts-ssr/_github/workflows/deploy.yaml +90 -39
- package/template-react-ts-ssr/package.json +2 -2
- package/template-vanilla/README.md +57 -25
- package/template-vanilla/_github/workflows/deploy.yaml +90 -39
- package/template-vanilla/package.json +5 -3
- package/template-vanilla-ts/README.md +57 -25
- package/template-vanilla-ts/_github/workflows/deploy.yaml +90 -39
- package/template-vanilla-ts/package.json +5 -3
- package/template-vue/README.md +57 -25
- package/template-vue/_github/workflows/deploy.yaml +90 -39
- package/template-vue/package.json +2 -2
- package/template-vue-ssr/README.md +57 -25
- package/template-vue-ssr/_github/workflows/deploy.yaml +90 -39
- package/template-vue-ssr/package.json +2 -2
- package/template-vue-ts/README.md +57 -25
- package/template-vue-ts/_github/workflows/deploy.yaml +90 -39
- package/template-vue-ts/package.json +2 -2
- package/template-vue-ts-ssr/README.md +57 -25
- package/template-vue-ts-ssr/_github/workflows/deploy.yaml +90 -39
- 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
|
-
- `
|
|
70
|
-
- `
|
|
71
|
-
- `
|
|
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}`;
|
package/lib/fs/copyFile.js
CHANGED
|
@@ -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}
|
|
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
|
-
* @
|
|
20
|
-
*
|
|
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
|
|
34
|
+
function withoutPlaceholderTarget(templateEnv, existingEnv = '') {
|
|
23
35
|
const existing = dotenv.parse(existingEnv);
|
|
24
|
-
const
|
|
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
|
-
.
|
|
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')
|
|
46
|
-
|
|
47
|
-
|
|
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
|
-
${
|
|
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.
|
|
4
|
+
"version": "1.13.0",
|
|
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.
|
|
83
|
+
"dprint": "^0.61.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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
81
|
-
|
|
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
|
-
|
|
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
|
-
|
|
116
|
+
### Deploying by hand
|
|
90
117
|
|
|
91
118
|
```sh
|
|
92
|
-
|
|
119
|
+
your-package-manager-run-here deploy
|
|
93
120
|
```
|
|
94
121
|
|
|
95
|
-
|
|
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
|
-
|
|
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
|
-
#
|
|
2
|
-
#
|
|
3
|
-
#
|
|
4
|
-
#
|
|
5
|
-
#
|
|
6
|
-
#
|
|
7
|
-
|
|
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
|
-
|
|
9
|
+
pull_request:
|
|
26
10
|
push:
|
|
27
|
-
|
|
28
|
-
|
|
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:
|
|
20
|
+
group: deploy-${{ github.ref }}
|
|
21
|
+
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
|
|
33
22
|
|
|
34
23
|
jobs:
|
|
35
|
-
|
|
24
|
+
test:
|
|
36
25
|
runs-on: ubuntu-latest
|
|
37
26
|
steps:
|
|
38
27
|
- name: Checkout code
|
|
39
|
-
uses: actions/checkout@
|
|
28
|
+
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
40
29
|
with:
|
|
41
|
-
|
|
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@
|
|
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
|
-
#
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
run:
|
|
58
|
-
|
|
59
|
-
|
|
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
|
-
|
|
62
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
81
|
-
|
|
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
|
-
|
|
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
|
-
|
|
116
|
+
### Deploying by hand
|
|
90
117
|
|
|
91
118
|
```sh
|
|
92
|
-
|
|
119
|
+
your-package-manager-run-here deploy
|
|
93
120
|
```
|
|
94
121
|
|
|
95
|
-
|
|
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
|
-
|
|
145
|
+
Leave out `registry=` and `scope=` for a private package on npmjs.com.
|
|
98
146
|
|
|
99
147
|
## Keep Going!
|
|
100
148
|
|