@harperfast/template-vue-studio 1.13.5 → 1.13.7
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/.agents/skills/harper-best-practices/AGENTS.md +1260 -1113
- package/.agents/skills/harper-best-practices/rules/automatic-apis.md +118 -83
- package/.agents/skills/harper-best-practices/rules/checking-authentication.md +244 -256
- package/.agents/skills/harper-best-practices/rules/custom-resources.md +37 -42
- package/.agents/skills/harper-best-practices/rules/defining-relationships.md +86 -49
- package/.agents/skills/harper-best-practices/rules/deploying-from-ci.md +163 -170
- package/.agents/skills/harper-best-practices/rules/deploying-to-harper-fabric.md +128 -88
- package/.agents/skills/harper-best-practices/rules/load-env.md +27 -30
- package/.agents/skills/harper-best-practices/rules/programmatic-table-requests.md +184 -155
- package/.agents/skills/harper-best-practices/rules/querying-rest-apis.md +146 -94
- package/.agents/skills/harper-best-practices/rules/schema-design-tooling.md +60 -77
- package/.agents/skills/harper-best-practices/rules/v5-upgrade.md +52 -63
- package/.agents/skills/harper-best-practices/rules/vector-indexing.md +77 -68
- package/.agents/skills/harper-mcp/AGENTS.md +228 -155
- package/.agents/skills/harper-mcp/rules/custom-mcp-tools.md +35 -41
- package/.agents/skills/harper-mcp/rules/enabling-mcp.md +104 -92
- package/.agents/skills/harper-mcp/rules/rate-limiting.md +95 -28
- package/agent/skills/harper-best-practices/AGENTS.md +1260 -1113
- package/agent/skills/harper-best-practices/rules/automatic-apis.md +118 -83
- package/agent/skills/harper-best-practices/rules/checking-authentication.md +244 -256
- package/agent/skills/harper-best-practices/rules/custom-resources.md +37 -42
- package/agent/skills/harper-best-practices/rules/defining-relationships.md +86 -49
- package/agent/skills/harper-best-practices/rules/deploying-from-ci.md +163 -170
- package/agent/skills/harper-best-practices/rules/deploying-to-harper-fabric.md +128 -88
- package/agent/skills/harper-best-practices/rules/load-env.md +27 -30
- package/agent/skills/harper-best-practices/rules/programmatic-table-requests.md +184 -155
- package/agent/skills/harper-best-practices/rules/querying-rest-apis.md +146 -94
- package/agent/skills/harper-best-practices/rules/schema-design-tooling.md +60 -77
- package/agent/skills/harper-best-practices/rules/v5-upgrade.md +52 -63
- package/agent/skills/harper-best-practices/rules/vector-indexing.md +77 -68
- package/agent/skills/harper-mcp/AGENTS.md +228 -155
- package/agent/skills/harper-mcp/rules/custom-mcp-tools.md +35 -41
- package/agent/skills/harper-mcp/rules/enabling-mcp.md +104 -92
- package/agent/skills/harper-mcp/rules/rate-limiting.md +95 -28
- package/package.json +1 -1
- package/skills-lock.json +2 -2
|
@@ -23,8 +23,8 @@ metadata:
|
|
|
23
23
|
- reference/v5/operations-api/operations.md#Retrying an activation
|
|
24
24
|
- reference/v5/operations-api/operations.md#`list_deployments`
|
|
25
25
|
- reference/v5/operations-api/operations.md#`get_job`
|
|
26
|
-
sourceCommit:
|
|
27
|
-
inputHash:
|
|
26
|
+
sourceCommit: 489477b2259ba148f4e526ea4b5cd24041ceec03
|
|
27
|
+
inputHash: 53279ae8c94cde2b
|
|
28
28
|
---
|
|
29
29
|
|
|
30
30
|
# Deploying to Harper Fabric
|
|
@@ -39,148 +39,186 @@ Apply this rule when deploying a Harper application to a remote Harper Fabric cl
|
|
|
39
39
|
|
|
40
40
|
## How It Works
|
|
41
41
|
|
|
42
|
-
1. **
|
|
42
|
+
1. **Authenticate against the cluster**: Run `harper login` once, pointing at the cluster's Application URL (found on **Config → Overview**). The CLI stores the token and sets the URL as the default target. If the current directory has a `.env` file, and neither that file nor your environment sets `HARPER_CLI_TARGET` or `CLI_TARGET`, login appends `HARPER_CLI_TARGET` to it.
|
|
43
43
|
|
|
44
44
|
```bash
|
|
45
45
|
harper login <Application URL>
|
|
46
46
|
# Provide cluster username and password when prompted
|
|
47
47
|
```
|
|
48
48
|
|
|
49
|
-
For CI/CD pipelines, use workload identity (OIDC) or a refresh token from `harper login --for-ci` instead of a password. See [deploying-from-ci.md](deploying-from-ci.md) for a complete GitHub Actions workflow. For a one-off command, `auth_username=` and `auth_password=`
|
|
49
|
+
For CI/CD pipelines, use workload identity (OIDC) or a refresh token from `harper login --for-ci` instead of a password. See [deploying-from-ci.md](deploying-from-ci.md) for a complete GitHub Actions workflow. For a one-off command, `auth_username=` and `auth_password=` are available but not recommended for production.
|
|
50
50
|
|
|
51
|
-
2. **Deploy the application**: Run `harper deploy` with the required parameters.
|
|
51
|
+
2. **Deploy the application**: Run `harper deploy` with the required parameters. A bare `target` host defaults to `https://<host>:9925`. Use `restart=rolling` for a staggered, zero-downtime restart across the cluster. Pass `replicated=false` to restrict the deploy to the single node you called; on Harper Fabric, omit it to reach every node.
|
|
52
52
|
|
|
53
53
|
```bash
|
|
54
54
|
harper deploy \
|
|
55
55
|
project=<name> \
|
|
56
56
|
package=<package> \
|
|
57
57
|
target=<remote> \
|
|
58
|
-
restart=
|
|
58
|
+
restart=rolling \
|
|
59
59
|
replicated=true
|
|
60
60
|
```
|
|
61
61
|
|
|
62
|
-
|
|
62
|
+
Key parameters:
|
|
63
|
+
|
|
64
|
+
| Parameter | Description |
|
|
65
|
+
| --------------------- | ------------------------------------------------------------------------------------- |
|
|
66
|
+
| `package=<reference>` | npm, GitHub, or tarball reference. Omit to deploy current directory. |
|
|
67
|
+
| `target=<url>` | Remote Harper instance URL. Bare host defaults to `https://<host>:9925`. |
|
|
68
|
+
| `restart=rolling` | Restart nodes one at a time; each stays in rotation while it restarts. |
|
|
69
|
+
| `replicated=false` | Deploy to the called node only. |
|
|
70
|
+
| `wait=false` | With `restart=rolling`, exit after the called node takes the release. |
|
|
71
|
+
| `wait_timeout=<ms>` | With `restart=rolling`, maximum wait time per node. Default: ten minutes per node. |
|
|
72
|
+
| `activate=false` | Build and install without making the release live. Cannot be combined with `restart`. |
|
|
73
|
+
| `ref=<committish>` | Branch, tag, or commit SHA to deploy. Resolved to SHA. Implies `by_ref`. |
|
|
74
|
+
| `json=true` | Print output as JSON instead of YAML. |
|
|
63
75
|
|
|
64
76
|
3. **Choose a package source**: The `package` field accepts any valid npm dependency value.
|
|
65
77
|
|
|
66
|
-
|
|
|
67
|
-
|
|
|
68
|
-
|
|
|
69
|
-
|
|
|
70
|
-
|
|
|
71
|
-
|
|
|
78
|
+
| Format | Example |
|
|
79
|
+
| ----------------------- | --------------------------------------------------------------------------------------------- |
|
|
80
|
+
| Current local directory | Omit `package` |
|
|
81
|
+
| npm package | `package="@harperdb/status-check"` |
|
|
82
|
+
| GitHub (public) | `package="HarperFast/status-check"` or `package="https://github.com/HarperFast/status-check"` |
|
|
83
|
+
| Private repo (SSH) | `package="git+ssh://git@github.com:HarperDB/secret-app.git"` |
|
|
84
|
+
| Tarball | `package="https://example.com/application.tar.gz"` |
|
|
72
85
|
|
|
73
86
|
For git tags, use the `semver` directive: `HarperFast/application-template#semver:v1.0.0`. For an SSH-based private repo, register the key with `add_ssh_key` first.
|
|
74
87
|
|
|
75
|
-
4. **Provision credentials for private repositories**: Run `harper deploy setup=true` once per component and source. (With `provider=github-actions`, it sets up GitHub Actions OIDC deploys instead.) This requires `super_user` privileges
|
|
88
|
+
4. **Provision credentials for private repositories**: Run `harper deploy setup=true` once per component and source. (With `provider=github-actions`, it sets up GitHub Actions OIDC deploys instead.) This requires `super_user` privileges — run it with an administrative credential, not the CI identity it provisions for.
|
|
76
89
|
|
|
77
90
|
```bash
|
|
78
91
|
harper deploy setup=true
|
|
79
92
|
```
|
|
80
93
|
|
|
81
|
-
The
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
94
|
+
The setup flow:
|
|
95
|
+
- Fetches the cluster's public key with `get_secrets_public_key`.
|
|
96
|
+
- Encrypts the token locally into an `enc:v1:` envelope.
|
|
97
|
+
- Stores only the ciphertext with `set_secret` in the component-scoped tier — never in the global `processEnv` tier that every component and child process can read.
|
|
98
|
+
- Grants the component permission to resolve it with `grant_secret`.
|
|
99
|
+
|
|
100
|
+
Prefer a **fine-grained** personal access token scoped to **Contents: Read-only** on the target repository. Avoid the `gh` CLI session token, which carries `read:org`, `gist`, `workflow`, and `repo` scopes across your whole account. The encrypted token is durable and replayed on every cold deploy and rollback, so use the narrowest credential that does the job.
|
|
86
101
|
|
|
87
|
-
|
|
102
|
+
Then deploy with `credential=true`:
|
|
88
103
|
|
|
89
104
|
```bash
|
|
90
105
|
harper deploy by_ref=true credential=true restart=true replicated=true
|
|
91
106
|
```
|
|
92
107
|
|
|
93
|
-
5. **
|
|
108
|
+
5. **Deploy by reference for a reproducible source**: `by_ref=true` sends a pinned git reference instead of uploading the working directory, and the cluster fetches and builds that exact commit. It resolves the repository's `origin` remote and the current commit, then deploys `package=git+https://github.com/<owner>/<repo>.git#<full commit SHA>`.
|
|
94
109
|
|
|
95
|
-
```
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
110
|
+
```bash
|
|
111
|
+
harper deploy by_ref=true restart=true replicated=true
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Deploy a specific tag or commit with `ref`:
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
harper deploy ref=v1.2.0 restart=true replicated=true
|
|
118
|
+
harper deploy ref=9f8c2a1 restart=true replicated=true
|
|
102
119
|
```
|
|
103
120
|
|
|
104
|
-
|
|
121
|
+
Tags and branches are resolved to a full commit SHA before the deploy is sent. A `ref` that cannot be resolved stops the deploy — run `git fetch` and retry, or pass a full commit SHA. A full commit SHA is accepted directly with no resolution step. Valid refs must be in `refs/heads/*` or `refs/tags/*` if qualified; a ref like `refs/pull/123/head` is rejected up front even if your local checkout can resolve it. Commit and push before deploying — the cluster clones from the remote and only sees pushed commits.
|
|
122
|
+
- On a GitHub Actions `pull_request` run, `by_ref` deploys the pull request's head commit. If the event payload isn't readable, the deploy stops; pass the commit explicitly:
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
harper deploy ref=${{ github.event.pull_request.head.sha }} restart=true replicated=true
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
6. **Activate a staged build**: Make a staged build live using its `deployment_id`. Pass `restart` here, not on the stage step. Takes no `package`, `payload`, `credentials`, install options, or `urlPath`/`host` — those are rejected rather than ignored.
|
|
105
129
|
|
|
106
130
|
```json
|
|
107
131
|
{
|
|
108
|
-
"
|
|
109
|
-
"
|
|
132
|
+
"operation": "deploy_component",
|
|
133
|
+
"project": "my-app",
|
|
134
|
+
"deployment_id": "a3f8c2d1-..."
|
|
110
135
|
}
|
|
111
136
|
```
|
|
112
137
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
6. **Activate a staged build or roll back**: Pass `deployment_id` with `restart` to make a staged build live, or to restore a release a later deploy replaced, with no rebuild or reinstall. Pass `restart` here rather than on the stage.
|
|
138
|
+
Or via the CLI:
|
|
116
139
|
|
|
117
140
|
```bash
|
|
118
141
|
harper deploy project=<name> deployment_id=<id> restart=true
|
|
119
142
|
```
|
|
120
143
|
|
|
121
|
-
|
|
144
|
+
7. **Stage a build for later activation**: Pass `activate=false` (`activate: false` in the operation) to build and install without making the release live. `activate: false` cannot be combined with `restart`.
|
|
122
145
|
|
|
123
146
|
```json
|
|
124
|
-
{
|
|
147
|
+
{
|
|
148
|
+
"operation": "deploy_component",
|
|
149
|
+
"project": "my-app",
|
|
150
|
+
"package": "npm:@my-org/my-app@1.2.3",
|
|
151
|
+
"activate": false
|
|
152
|
+
}
|
|
125
153
|
```
|
|
126
154
|
|
|
127
|
-
|
|
128
|
-
- Kept releases and staged builds count against `deployment.stagingRetention.maxCount` (`stagingRetention` default: `5`). Each kept release is a full installed copy of the component, `node_modules` included, so budget disk for it. `0` keeps no replaced releases.
|
|
129
|
-
|
|
130
|
-
7. **Deploy by reference for a reproducible source**: `by_ref=true` sends a pinned git reference instead of uploading the working directory, and the cluster fetches and builds that exact commit. It resolves the repository's `origin` remote and the current commit, then deploys `package=git+https://github.com/<owner>/<repo>.git#<full commit SHA>`. Defaults to `HEAD`.
|
|
155
|
+
The response names the artifact that is now waiting:
|
|
131
156
|
|
|
132
|
-
```
|
|
133
|
-
|
|
157
|
+
```json
|
|
158
|
+
{
|
|
159
|
+
"deployment_id": "a3f8c2d1-...",
|
|
160
|
+
"message": "Staged: my-app. Deploy it with deploy_component deployment_id=a3f8c2d1-..."
|
|
161
|
+
}
|
|
134
162
|
```
|
|
135
163
|
|
|
136
|
-
|
|
164
|
+
The response includes a `deployment_id` naming the staged artifact. Staged builds and replaced releases together count against `deployment.stagingRetention.maxCount` (default `5`). Each kept release is a full installed copy of the component, `node_modules` included. The oldest are pruned at the next deploy or startup.
|
|
165
|
+
- `404` means the id never existed on that node, was pruned, or the release was replaced and not kept. A `409` means the build exists but cannot be activated (e.g., belongs to another component, or files changed after staging).
|
|
137
166
|
|
|
138
|
-
|
|
139
|
-
harper deploy ref=v1.2.0 restart=true replicated=true
|
|
140
|
-
harper deploy ref=9f8c2a1 restart=true replicated=true
|
|
141
|
-
```
|
|
167
|
+
8. **Roll back to a previous release**: Use `list_deployments` to find the `deployment_id` of the release to restore. Then activate that id with `restart`. This swaps in the exact installed release with no fetch, rebuild, or reinstall. The release it replaces is kept in turn, so you can go forward again the same way.
|
|
142
168
|
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
169
|
+
```json
|
|
170
|
+
{
|
|
171
|
+
"operation": "deploy_component",
|
|
172
|
+
"project": "my-app",
|
|
173
|
+
"deployment_id": "<id of the deployment you want back>",
|
|
174
|
+
"restart": true
|
|
175
|
+
}
|
|
176
|
+
```
|
|
147
177
|
|
|
148
|
-
|
|
178
|
+
9. **Check certification after a rolling deploy**: A deploy with `"restart": "rolling"` certifies the release on each node using a canary worker before rolling it out. The deploy response includes a `certification` field:
|
|
149
179
|
|
|
150
180
|
| `certification` | Meaning |
|
|
151
181
|
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
152
182
|
| `certified` | The canary loaded the release; rollout proceeded. |
|
|
153
183
|
| `uncertified` | The rollout went on unchecked: the component ran nothing as it loaded (`loadComponent: dev-only`, an absent `if-installed` component, or safe mode), or no worker was replaced. |
|
|
154
|
-
| `unavailable` | Deploy restarted unchecked (no worker loads the component, `isolated` setting changed, already live, or `file
|
|
184
|
+
| `unavailable` | Deploy restarted unchecked (no worker loads the component, `isolated` setting changed, already live, or `package: file:<dir>` source). |
|
|
155
185
|
| `not-requested` | The deploy did not restart. |
|
|
156
|
-
- **A rejected release fails the deploy.** If the canary throws while loading the component, exits, or doesn't report within a minute, the deploy fails with `400`. The release it replaced is made live again, and nothing is replicated to other nodes.
|
|
157
|
-
- **A release with nothing to go back to fails closed.** A rejected first deploy, or one whose previous release was not kept, stays on disk, but no worker on that node loads it, even after Harper restarts. `get_status` reports the component as failed and says why. Deploy a
|
|
186
|
+
- **A rejected release fails the deploy.** If the canary throws while loading the component, exits, or doesn't report within a minute, the deploy fails with `400`. The release it replaced is made live again, and nothing is replicated to other nodes. A restart that stops before the canary decides is reported with `status: "interrupted"`.
|
|
187
|
+
- **A release with nothing to go back to fails closed.** A rejected first deploy, or one whose previous release was not kept, stays on disk, but no worker on that node loads it, even after Harper restarts. `get_status` reports the component as failed and says why. Deploy a fixed release, or activate the same `deployment_id` again with `restart` once the cause is fixed.
|
|
158
188
|
- Another deploy or `drop_component` of the component on that node is refused with `409` until the rollout has finished.
|
|
159
189
|
|
|
160
|
-
|
|
190
|
+
10. **Check rolling deploy job status**: A `deploy_component` with `"restart": "rolling"` returns a `restartJobId`. Call `get_job` on the node that received the deploy — `system.hdb_job` is not replicated.
|
|
161
191
|
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
192
|
+
```json
|
|
193
|
+
{ "operation": "get_job", "id": "<restartJobId>" }
|
|
194
|
+
```
|
|
165
195
|
|
|
166
|
-
|
|
167
|
-
|
|
196
|
+
`get_job` returns status `COMPLETE`, `IN_PROGRESS`, or `ERROR`. It answers only on the node that ran the job — `system.hdb_job` is not replicated. For a rolling deploy, that is the node that received the deploy. A deploy-only role that polls for rolling deploys must include `get_job` in its operations allowlist. The job ends `COMPLETE` on success, or `ERROR` with a `message` listing each node's outcome under `activated`.
|
|
197
|
+
|
|
198
|
+
11. **Monitor `list_deployments` correctly**: A deploy in progress reads `pending`, or `loading` once its release has started loading. A rolling deploy's record reads `rolling_out` until the job has visited every node; filter `list_deployments` without `status` and check each record's `status` is a finished one (`success`, `failed`, `staged`, or `partial`). `completed_at` alone does not indicate completion, since a `rolling_out` record already has it.
|
|
199
|
+
|
|
200
|
+
```json
|
|
201
|
+
{
|
|
202
|
+
"operation": "list_deployments",
|
|
203
|
+
"project": "my-app",
|
|
204
|
+
"limit": 20
|
|
205
|
+
}
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
- The `list_deployments` response strips `payload_blob` and replaces it with `payload_blob_present`; use `get_deployment_payload` to retrieve the tarball.
|
|
168
209
|
|
|
169
210
|
## Examples
|
|
170
211
|
|
|
171
|
-
### Full rolling deploy from a
|
|
212
|
+
### Full rolling deploy from a git tag
|
|
172
213
|
|
|
173
214
|
```bash
|
|
174
|
-
# Authenticate once
|
|
175
215
|
harper login https://my-cluster.harperdbcloud.com
|
|
176
|
-
|
|
177
|
-
# Deploy a pinned release with rolling restart
|
|
178
216
|
harper deploy \
|
|
179
217
|
project=my-app \
|
|
180
218
|
ref=v1.2.0 \
|
|
181
|
-
target=https://my-cluster.harperdbcloud.com \
|
|
182
219
|
restart=rolling \
|
|
183
|
-
replicated=true
|
|
220
|
+
replicated=true \
|
|
221
|
+
credential=true
|
|
184
222
|
```
|
|
185
223
|
|
|
186
224
|
### Stage a build, then activate in a maintenance window
|
|
@@ -203,7 +241,7 @@ Response:
|
|
|
203
241
|
}
|
|
204
242
|
```
|
|
205
243
|
|
|
206
|
-
Activate later:
|
|
244
|
+
Activate later with restart:
|
|
207
245
|
|
|
208
246
|
```json
|
|
209
247
|
{
|
|
@@ -214,27 +252,30 @@ Activate later:
|
|
|
214
252
|
}
|
|
215
253
|
```
|
|
216
254
|
|
|
217
|
-
### Roll back
|
|
255
|
+
### Roll back using list_deployments
|
|
218
256
|
|
|
219
257
|
```json
|
|
220
|
-
{
|
|
221
|
-
"operation": "list_deployments",
|
|
222
|
-
"project": "my-app"
|
|
223
|
-
}
|
|
258
|
+
{ "operation": "list_deployments", "project": "my-app", "limit": 10 }
|
|
224
259
|
```
|
|
225
260
|
|
|
226
|
-
Then:
|
|
227
|
-
|
|
228
261
|
```json
|
|
229
262
|
{
|
|
230
263
|
"operation": "deploy_component",
|
|
231
264
|
"project": "my-app",
|
|
232
|
-
"deployment_id": "<id
|
|
265
|
+
"deployment_id": "<previous-deployment-id>",
|
|
233
266
|
"restart": true
|
|
234
267
|
}
|
|
235
268
|
```
|
|
236
269
|
|
|
237
|
-
###
|
|
270
|
+
### Check a rolling deploy job
|
|
271
|
+
|
|
272
|
+
```json
|
|
273
|
+
{ "operation": "get_job", "id": "4a982782-929a-4507-8794-26dae1132def" }
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
The job ends `COMPLETE` when every node has taken the release, or `ERROR` with node-level detail if any node did not.
|
|
277
|
+
|
|
278
|
+
### Certification rejection response
|
|
238
279
|
|
|
239
280
|
```json
|
|
240
281
|
{
|
|
@@ -254,14 +295,13 @@ Then:
|
|
|
254
295
|
|
|
255
296
|
## Notes
|
|
256
297
|
|
|
257
|
-
- `
|
|
258
|
-
-
|
|
259
|
-
- `
|
|
260
|
-
- `
|
|
261
|
-
- `
|
|
262
|
-
-
|
|
263
|
-
- `get_job`
|
|
264
|
-
-
|
|
265
|
-
-
|
|
266
|
-
-
|
|
267
|
-
- `super_user` is required to run `harper deploy setup=true`.
|
|
298
|
+
- `replicated=false` restricts a deploy to the single node you called. On Harper Fabric, omit this parameter to reach every node.
|
|
299
|
+
- `restart=rolling` cannot be combined with `activate=false`.
|
|
300
|
+
- `deployment_id` activation takes no `package`, `payload`, `credentials`, install options, or `urlPath`/`host` — supplying them is rejected.
|
|
301
|
+
- `file:` directory sources cannot be staged with `activate=false` and are not kept as rollback targets.
|
|
302
|
+
- `deployment.stagingRetention.maxCount` (default `5`) caps staged builds and kept replaced releases together per component. At the default, budget disk for up to five extra copies per component, `node_modules` included.
|
|
303
|
+
- A deploy-only role that waits for rolling deploys must include `get_job` in its operations allowlist.
|
|
304
|
+
- `get_job` answers only on the node that ran the job — `system.hdb_job` is not replicated.
|
|
305
|
+
- The `enc:v1:` envelope is the only form of the token that ever leaves your machine or appears in API logs.
|
|
306
|
+
- The secret provisioned by `harper deploy setup=true` is stored scoped to the component, never in the global `processEnv` tier.
|
|
307
|
+
- For creating the cluster itself, see [creating-a-fabric-account-and-cluster.md](creating-a-fabric-account-and-cluster.md). For full CI/CD pipeline setup, see [deploying-from-ci.md](deploying-from-ci.md).
|
|
@@ -7,7 +7,7 @@ metadata:
|
|
|
7
7
|
mode: generate
|
|
8
8
|
sources:
|
|
9
9
|
- reference/v5/environment-variables/overview.md
|
|
10
|
-
sourceCommit:
|
|
10
|
+
sourceCommit: 489477b2259ba148f4e526ea4b5cd24041ceec03
|
|
11
11
|
inputHash: 51b7b4f21b275eec
|
|
12
12
|
---
|
|
13
13
|
|
|
@@ -19,11 +19,11 @@ Instructions for the agent to follow when loading environment variables from `.e
|
|
|
19
19
|
|
|
20
20
|
## When to Use
|
|
21
21
|
|
|
22
|
-
Apply this rule when a Harper application needs to supply secrets, API endpoints, or other configuration values to component code via `process.env` without hardcoding them. Use this whenever a `.env` file must be loaded at application startup.
|
|
22
|
+
Apply this rule when a Harper application needs to supply secrets, API endpoints, or other configuration values to component code via `process.env` without hardcoding them. Use this whenever a `.env` file must be loaded at application startup before other components run.
|
|
23
23
|
|
|
24
24
|
## How It Works
|
|
25
25
|
|
|
26
|
-
1. **Declare `loadEnv` first in `config.yaml`**: Place `loadEnv` before all other components so environment variables are available when dependent components start.
|
|
26
|
+
1. **Declare `loadEnv` first in `config.yaml`**: Place `loadEnv` before all other components so environment variables are available when dependent components start. Harper is single-process, so variables loaded onto `process.env` are shared across all components.
|
|
27
27
|
|
|
28
28
|
```yaml
|
|
29
29
|
# config.yaml — loadEnv must come first
|
|
@@ -31,13 +31,11 @@ Apply this rule when a Harper application needs to supply secrets, API endpoints
|
|
|
31
31
|
files: '.env'
|
|
32
32
|
```
|
|
33
33
|
|
|
34
|
-
2. **Set the `files` option
|
|
34
|
+
2. **Specify files to load**: Set the `files` option to a path, glob pattern, or list of paths. This is the only required option.
|
|
35
35
|
|
|
36
|
-
3. **
|
|
36
|
+
3. **Control override behavior**: By default, existing environment variables take precedence over values in `.env` files. Set `override: true` to make loaded values overwrite existing environment variables.
|
|
37
37
|
|
|
38
|
-
4. **
|
|
39
|
-
|
|
40
|
-
5. **Load multiple files when needed**: Specify a list or a glob pattern under `files`. Files are loaded in the order specified.
|
|
38
|
+
4. **Access values in component code**: After loading, all values from the specified files are available on `process.env` throughout your components.
|
|
41
39
|
|
|
42
40
|
### Configuration Options
|
|
43
41
|
|
|
@@ -48,26 +46,13 @@ Apply this rule when a Harper application needs to supply secrets, API endpoints
|
|
|
48
46
|
|
|
49
47
|
## Examples
|
|
50
48
|
|
|
51
|
-
**Basic
|
|
49
|
+
**Basic single file:**
|
|
52
50
|
|
|
53
51
|
```yaml
|
|
54
52
|
loadEnv:
|
|
55
53
|
files: '.env'
|
|
56
54
|
```
|
|
57
55
|
|
|
58
|
-
**Full `config.yaml` with `loadEnv` declared first:**
|
|
59
|
-
|
|
60
|
-
```yaml
|
|
61
|
-
# config.yaml — loadEnv must come first
|
|
62
|
-
loadEnv:
|
|
63
|
-
files: '.env'
|
|
64
|
-
|
|
65
|
-
rest: true
|
|
66
|
-
|
|
67
|
-
myApp:
|
|
68
|
-
files: './src/*.js'
|
|
69
|
-
```
|
|
70
|
-
|
|
71
56
|
**Override existing environment variables:**
|
|
72
57
|
|
|
73
58
|
```yaml
|
|
@@ -76,7 +61,7 @@ loadEnv:
|
|
|
76
61
|
override: true
|
|
77
62
|
```
|
|
78
63
|
|
|
79
|
-
**
|
|
64
|
+
**Multiple explicit files** (loaded in order specified):
|
|
80
65
|
|
|
81
66
|
```yaml
|
|
82
67
|
loadEnv:
|
|
@@ -85,18 +70,30 @@ loadEnv:
|
|
|
85
70
|
- '.env.local'
|
|
86
71
|
```
|
|
87
72
|
|
|
88
|
-
**
|
|
73
|
+
**Glob pattern:**
|
|
89
74
|
|
|
90
75
|
```yaml
|
|
91
76
|
loadEnv:
|
|
92
77
|
files: 'env-vars/*'
|
|
93
78
|
```
|
|
94
79
|
|
|
80
|
+
**Full `config.yaml` with dependent components:**
|
|
81
|
+
|
|
82
|
+
```yaml
|
|
83
|
+
# config.yaml — loadEnv must come first
|
|
84
|
+
loadEnv:
|
|
85
|
+
files: '.env'
|
|
86
|
+
|
|
87
|
+
rest: true
|
|
88
|
+
|
|
89
|
+
myApp:
|
|
90
|
+
files: './src/*.js'
|
|
91
|
+
```
|
|
92
|
+
|
|
95
93
|
## Notes
|
|
96
94
|
|
|
97
|
-
- `loadEnv` is built into Harper —
|
|
98
|
-
-
|
|
99
|
-
-
|
|
100
|
-
-
|
|
101
|
-
- For production credentials, prefer the encrypted secrets store over a committed `.env` file.
|
|
102
|
-
- Individual `.env` values can also be stored encrypted so plaintext never reaches the API, logs, or replication payload.
|
|
95
|
+
- `loadEnv` is built into Harper — do not install it separately. Only declare it in `config.yaml`.
|
|
96
|
+
- `loadEnv` supplies **application** environment variables for component code. It does **not** configure Harper itself.
|
|
97
|
+
- Harper's own configuration is composed at startup **before** any `loadEnv` runs. Variables such as `HARPER_CONFIG`, `HARPER_SET_CONFIG`, and `HARPER_DEFAULT_CONFIG` delivered through a `.env` file are read too late and are ignored. Set Harper configuration in the configuration file or export variables in the real process/container environment before Harper starts.
|
|
98
|
+
- A component's `.env` file can be managed remotely via the Operations API (`get_env_keys`, `set_env_value`, `delete_env_value`). Changes reach running code only after worker threads restart.
|
|
99
|
+
- For production credentials, prefer the encrypted secrets store over a committed `.env` file. Individual `.env` values can also be stored encrypted. See [Encrypted Environment Values](encrypted-values.md) and [Secrets](secrets.md).
|