@rcpooley/concord 0.1.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/LICENSE +21 -0
- package/README.md +318 -0
- package/bin/concord.service +69 -0
- package/dist/age.d.ts +20 -0
- package/dist/age.d.ts.map +1 -0
- package/dist/age.js +58 -0
- package/dist/age.js.map +1 -0
- package/dist/cli/main.d.ts +3 -0
- package/dist/cli/main.d.ts.map +1 -0
- package/dist/cli/main.js +301 -0
- package/dist/cli/main.js.map +1 -0
- package/dist/daemon.d.ts +4 -0
- package/dist/daemon.d.ts.map +1 -0
- package/dist/daemon.js +394 -0
- package/dist/daemon.js.map +1 -0
- package/dist/eval-config.d.ts +2 -0
- package/dist/eval-config.d.ts.map +1 -0
- package/dist/eval-config.js +45 -0
- package/dist/eval-config.js.map +1 -0
- package/dist/exec.d.ts +168 -0
- package/dist/exec.d.ts.map +1 -0
- package/dist/exec.js +313 -0
- package/dist/exec.js.map +1 -0
- package/dist/git.d.ts +59 -0
- package/dist/git.d.ts.map +1 -0
- package/dist/git.js +265 -0
- package/dist/git.js.map +1 -0
- package/dist/hook.d.ts +37 -0
- package/dist/hook.d.ts.map +1 -0
- package/dist/hook.js +89 -0
- package/dist/hook.js.map +1 -0
- package/dist/index.d.ts +18 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +15 -0
- package/dist/index.js.map +1 -0
- package/dist/init.d.ts +76 -0
- package/dist/init.d.ts.map +1 -0
- package/dist/init.js +236 -0
- package/dist/init.js.map +1 -0
- package/dist/loader.d.ts +35 -0
- package/dist/loader.d.ts.map +1 -0
- package/dist/loader.js +230 -0
- package/dist/loader.js.map +1 -0
- package/dist/module.d.ts +116 -0
- package/dist/module.d.ts.map +1 -0
- package/dist/module.js +100 -0
- package/dist/module.js.map +1 -0
- package/dist/modules/apt/index.d.ts +45 -0
- package/dist/modules/apt/index.d.ts.map +1 -0
- package/dist/modules/apt/index.js +249 -0
- package/dist/modules/apt/index.js.map +1 -0
- package/dist/modules/apt/schema.d.ts +63 -0
- package/dist/modules/apt/schema.d.ts.map +1 -0
- package/dist/modules/apt/schema.js +75 -0
- package/dist/modules/apt/schema.js.map +1 -0
- package/dist/modules/checkout/index.d.ts +88 -0
- package/dist/modules/checkout/index.d.ts.map +1 -0
- package/dist/modules/checkout/index.js +382 -0
- package/dist/modules/checkout/index.js.map +1 -0
- package/dist/modules/checkout/schema.d.ts +52 -0
- package/dist/modules/checkout/schema.d.ts.map +1 -0
- package/dist/modules/checkout/schema.js +132 -0
- package/dist/modules/checkout/schema.js.map +1 -0
- package/dist/modules/cloudflare/api.d.ts +64 -0
- package/dist/modules/cloudflare/api.d.ts.map +1 -0
- package/dist/modules/cloudflare/api.js +98 -0
- package/dist/modules/cloudflare/api.js.map +1 -0
- package/dist/modules/cloudflare/index.d.ts +74 -0
- package/dist/modules/cloudflare/index.d.ts.map +1 -0
- package/dist/modules/cloudflare/index.js +374 -0
- package/dist/modules/cloudflare/index.js.map +1 -0
- package/dist/modules/cloudflare/schema.d.ts +62 -0
- package/dist/modules/cloudflare/schema.d.ts.map +1 -0
- package/dist/modules/cloudflare/schema.js +85 -0
- package/dist/modules/cloudflare/schema.js.map +1 -0
- package/dist/modules/docker/index.d.ts +83 -0
- package/dist/modules/docker/index.d.ts.map +1 -0
- package/dist/modules/docker/index.js +470 -0
- package/dist/modules/docker/index.js.map +1 -0
- package/dist/modules/docker/registry.d.ts +35 -0
- package/dist/modules/docker/registry.d.ts.map +1 -0
- package/dist/modules/docker/registry.js +95 -0
- package/dist/modules/docker/registry.js.map +1 -0
- package/dist/modules/docker/render.d.ts +45 -0
- package/dist/modules/docker/render.d.ts.map +1 -0
- package/dist/modules/docker/render.js +162 -0
- package/dist/modules/docker/render.js.map +1 -0
- package/dist/modules/docker/schema.d.ts +231 -0
- package/dist/modules/docker/schema.d.ts.map +1 -0
- package/dist/modules/docker/schema.js +335 -0
- package/dist/modules/docker/schema.js.map +1 -0
- package/dist/modules/docker/sweeper.d.ts +64 -0
- package/dist/modules/docker/sweeper.d.ts.map +1 -0
- package/dist/modules/docker/sweeper.js +94 -0
- package/dist/modules/docker/sweeper.js.map +1 -0
- package/dist/modules/file/index.d.ts +79 -0
- package/dist/modules/file/index.d.ts.map +1 -0
- package/dist/modules/file/index.js +305 -0
- package/dist/modules/file/index.js.map +1 -0
- package/dist/modules/file/schema.d.ts +45 -0
- package/dist/modules/file/schema.d.ts.map +1 -0
- package/dist/modules/file/schema.js +114 -0
- package/dist/modules/file/schema.js.map +1 -0
- package/dist/modules/index.d.ts +20 -0
- package/dist/modules/index.d.ts.map +1 -0
- package/dist/modules/index.js +11 -0
- package/dist/modules/index.js.map +1 -0
- package/dist/modules/porkbun/api.d.ts +36 -0
- package/dist/modules/porkbun/api.d.ts.map +1 -0
- package/dist/modules/porkbun/api.js +62 -0
- package/dist/modules/porkbun/api.js.map +1 -0
- package/dist/modules/porkbun/index.d.ts +50 -0
- package/dist/modules/porkbun/index.d.ts.map +1 -0
- package/dist/modules/porkbun/index.js +236 -0
- package/dist/modules/porkbun/index.js.map +1 -0
- package/dist/modules/porkbun/schema.d.ts +38 -0
- package/dist/modules/porkbun/schema.d.ts.map +1 -0
- package/dist/modules/porkbun/schema.js +39 -0
- package/dist/modules/porkbun/schema.js.map +1 -0
- package/dist/modules/script/index.d.ts +43 -0
- package/dist/modules/script/index.d.ts.map +1 -0
- package/dist/modules/script/index.js +116 -0
- package/dist/modules/script/index.js.map +1 -0
- package/dist/modules/script/schema.d.ts +25 -0
- package/dist/modules/script/schema.d.ts.map +1 -0
- package/dist/modules/script/schema.js +63 -0
- package/dist/modules/script/schema.js.map +1 -0
- package/dist/modules/systemd/index.d.ts +93 -0
- package/dist/modules/systemd/index.d.ts.map +1 -0
- package/dist/modules/systemd/index.js +394 -0
- package/dist/modules/systemd/index.js.map +1 -0
- package/dist/modules/systemd/render.d.ts +41 -0
- package/dist/modules/systemd/render.d.ts.map +1 -0
- package/dist/modules/systemd/render.js +252 -0
- package/dist/modules/systemd/render.js.map +1 -0
- package/dist/modules/systemd/schema.d.ts +293 -0
- package/dist/modules/systemd/schema.d.ts.map +1 -0
- package/dist/modules/systemd/schema.js +302 -0
- package/dist/modules/systemd/schema.js.map +1 -0
- package/dist/modules/systemd/sweeper.d.ts +31 -0
- package/dist/modules/systemd/sweeper.d.ts.map +1 -0
- package/dist/modules/systemd/sweeper.js +77 -0
- package/dist/modules/systemd/sweeper.js.map +1 -0
- package/dist/plans.d.ts +132 -0
- package/dist/plans.d.ts.map +1 -0
- package/dist/plans.js +315 -0
- package/dist/plans.js.map +1 -0
- package/dist/records.d.ts +37 -0
- package/dist/records.d.ts.map +1 -0
- package/dist/records.js +100 -0
- package/dist/records.js.map +1 -0
- package/dist/registry.d.ts +38 -0
- package/dist/registry.d.ts.map +1 -0
- package/dist/registry.js +31 -0
- package/dist/registry.js.map +1 -0
- package/dist/runner.d.ts +48 -0
- package/dist/runner.d.ts.map +1 -0
- package/dist/runner.js +150 -0
- package/dist/runner.js.map +1 -0
- package/dist/scheduler.d.ts +36 -0
- package/dist/scheduler.d.ts.map +1 -0
- package/dist/scheduler.js +77 -0
- package/dist/scheduler.js.map +1 -0
- package/dist/schema.d.ts +762 -0
- package/dist/schema.d.ts.map +1 -0
- package/dist/schema.js +185 -0
- package/dist/schema.js.map +1 -0
- package/dist/secret.d.ts +24 -0
- package/dist/secret.d.ts.map +1 -0
- package/dist/secret.js +3 -0
- package/dist/secret.js.map +1 -0
- package/dist/ui.d.ts +62 -0
- package/dist/ui.d.ts.map +1 -0
- package/dist/ui.js +288 -0
- package/dist/ui.js.map +1 -0
- package/package.json +57 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Robert Pooley
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,318 @@
|
|
|
1
|
+
# Concord
|
|
2
|
+
|
|
3
|
+
A declarative config reconciler. You describe your hosts in a typed config
|
|
4
|
+
repo (containers, files, packages, systemd units, git checkouts, DNS
|
|
5
|
+
records) and push it. A small daemon pulls the repo, plans the difference
|
|
6
|
+
against reality and applies it.
|
|
7
|
+
|
|
8
|
+
**It does not replace the services it drives.** Docker keeps building and
|
|
9
|
+
supervising containers; systemd keeps supervising units; your DNS provider keeps
|
|
10
|
+
serving DNS. Concord says what should exist and drives their interfaces until it
|
|
11
|
+
does. Every module is a small, replaceable driver, so nothing home-rolled is
|
|
12
|
+
load-bearing.
|
|
13
|
+
|
|
14
|
+
This package is two things:
|
|
15
|
+
|
|
16
|
+
- **the reconciler**: the `concord` CLI and the `concord-daemon` that runs it on
|
|
17
|
+
a loop;
|
|
18
|
+
- **the schema library** your config repo imports, as types only, to get a
|
|
19
|
+
typechecked config.
|
|
20
|
+
|
|
21
|
+
> The package is scoped (`@rcpooley/concord`) because the bare name `concord` on
|
|
22
|
+
> the public npm registry is an unrelated package. Always run the CLI through an
|
|
23
|
+
> install (`npm run …`, or the global binary), never `npx concord`. npx falls
|
|
24
|
+
> back to the registry when a local bin is missing.
|
|
25
|
+
|
|
26
|
+
## How it works
|
|
27
|
+
|
|
28
|
+
- **One primary host runs the daemon.** It reaches every other host over ssh
|
|
29
|
+
(or locally, for itself), so the other hosts need sshd, a key the primary
|
|
30
|
+
trusts and the tools the modules drive (Docker, systemd, git). They don't
|
|
31
|
+
need Concord itself.
|
|
32
|
+
- **The config is a git repo you own.** It default-exports a `ConcordConfig`
|
|
33
|
+
from `concord.ts`: a host registry and an ordered list of modules.
|
|
34
|
+
- **Secrets are age-encrypted in the config repo.** Anyone with the public key
|
|
35
|
+
(`age.pub`, committed) can add a secret. Only the daemon holds the private
|
|
36
|
+
key, in its environment.
|
|
37
|
+
- **The daemon reconciles on an interval** (default 15 minutes), and early
|
|
38
|
+
when asked: on `SIGHUP` (`systemctl reload concord`) or on a GitHub push
|
|
39
|
+
webhook. Each cycle pulls the config, evaluates it, plans every module in
|
|
40
|
+
order, and applies. A failure aborts the rest of the run, and the daemon
|
|
41
|
+
never claims convergence for a run that errored. It logs the failure and
|
|
42
|
+
tries again next cycle.
|
|
43
|
+
- **How Concord runs is never decided by the config.** Every daemon setting is
|
|
44
|
+
an environment variable, so a broken config can't take away the mechanism
|
|
45
|
+
that would fix it.
|
|
46
|
+
|
|
47
|
+
## Install
|
|
48
|
+
|
|
49
|
+
On the host that will run the daemon, as the user it should run as (not
|
|
50
|
+
root). That user needs passwordless `sudo`, and the host needs systemd, git
|
|
51
|
+
and Node 20 or newer.
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
sudo npm install -g @rcpooley/concord # or without sudo, if your npm prefix is user-owned (nvm)
|
|
55
|
+
concord init
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
`concord init` checks those prerequisites, then:
|
|
59
|
+
|
|
60
|
+
- writes `/etc/concord.env` (root-only, 0600) with a **new age key** and an
|
|
61
|
+
empty `CONCORD_CONFIG_REPO`, and prints the key's public half for your config
|
|
62
|
+
repo's `age.pub`;
|
|
63
|
+
- writes `/etc/systemd/system/concord.service` for this user and this install
|
|
64
|
+
of node;
|
|
65
|
+
- enables and starts the service, which waits until it has a config repo.
|
|
66
|
+
|
|
67
|
+
Then point it at your config repo and restart:
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
sudoedit /etc/concord.env # set CONCORD_CONFIG_REPO
|
|
71
|
+
sudo systemctl restart concord
|
|
72
|
+
journalctl -u concord -f
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Or pass `--config-repo <url>` to `concord init` to skip that step. The daemon
|
|
76
|
+
needs read access to the repo, so use a URL its user can already fetch, for
|
|
77
|
+
example over ssh with a deploy key.
|
|
78
|
+
|
|
79
|
+
`concord init` is safe to re-run. An existing env file is never touched, since
|
|
80
|
+
it holds the key your secrets are encrypted to. An existing unit that differs
|
|
81
|
+
(after moving node, say) is replaced only with `--replace-unit`. `--dry-run`
|
|
82
|
+
shows what it would do.
|
|
83
|
+
|
|
84
|
+
## Usage
|
|
85
|
+
|
|
86
|
+
```
|
|
87
|
+
concord plan # pull config, compute the plan, change nothing
|
|
88
|
+
# --no-sync: plan the checkout as-is; --result FILE: JSON result
|
|
89
|
+
concord run # pull config, compute the plan, apply it
|
|
90
|
+
concord keygen # generate an age keypair
|
|
91
|
+
concord secret set KEY # encrypt stdin into the config repo's secrets.ts
|
|
92
|
+
concord secret list # list declared secret names
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Environment:
|
|
96
|
+
|
|
97
|
+
| Var | Purpose |
|
|
98
|
+
|---|---|
|
|
99
|
+
| `CONCORD_CONFIG_REPO` | git URL of the config repo (required for `run`/`plan` and the daemon) |
|
|
100
|
+
| `CONCORD_AGE_KEY` | age private key, which decrypts secrets at runtime (required likewise) |
|
|
101
|
+
| `CONCORD_HOME` | working dir, default `~/.concord` |
|
|
102
|
+
| `CONCORD_CONFIG_DIR` | override the config checkout path |
|
|
103
|
+
| `CONCORD_INTERVAL_SECONDS` | daemon: seconds between reconciles (default 900, minimum 30) |
|
|
104
|
+
| `CONCORD_HOOK_SECRET` | daemon: GitHub webhook HMAC secret; unset means no webhook |
|
|
105
|
+
| `CONCORD_HOOK_SOCKET` | daemon: webhook socket (default `/run/concord/hook.sock`) |
|
|
106
|
+
| `CONCORD_UI_SOCKET` | daemon: UI/API socket (default `/run/concord/ui.sock`; `off` disables) |
|
|
107
|
+
|
|
108
|
+
## Running the daemon
|
|
109
|
+
|
|
110
|
+
The daemon runs under systemd as an ordinary user with passwordless `sudo`
|
|
111
|
+
(the apt, file and systemd modules need it). `bin/concord.service` is the
|
|
112
|
+
template `concord init` renders the unit from. It reads its whole
|
|
113
|
+
configuration from `/etc/concord.env` (mode 0600, because it holds the age
|
|
114
|
+
key).
|
|
115
|
+
|
|
116
|
+
**Until `CONCORD_CONFIG_REPO` and `CONCORD_AGE_KEY` are both set, the daemon
|
|
117
|
+
waits.** It logs which ones are missing and does nothing else. It doesn't
|
|
118
|
+
exit, so systemd doesn't restart it in a loop. Set them, then
|
|
119
|
+
`sudo systemctl restart concord`. A reload won't do it, because systemd reads
|
|
120
|
+
the environment file only at start.
|
|
121
|
+
|
|
122
|
+
Day to day:
|
|
123
|
+
|
|
124
|
+
| | |
|
|
125
|
+
|---|---|
|
|
126
|
+
| Logs | `journalctl -u concord.service` |
|
|
127
|
+
| Reconcile now | `sudo systemctl reload concord` (SIGHUP to the daemon only). Never `systemctl kill -s HUP`, which signals every process in the unit and kills an apply in flight. |
|
|
128
|
+
| Stop | `sudo systemctl stop concord` finishes the cycle in flight first (up to 5 minutes) |
|
|
129
|
+
| Update | Concord never updates itself. The daemon logs a warning each cycle when a newer version exists: `sudo npm install -g @rcpooley/concord@<version>`, then `sudo systemctl restart concord`. |
|
|
130
|
+
|
|
131
|
+
**The webhook is optional.** With `CONCORD_HOOK_SECRET` set, the daemon listens
|
|
132
|
+
on `CONCORD_HOOK_SOCKET` for GitHub push deliveries, verifies the HMAC, and
|
|
133
|
+
reconciles. It never parses the payload, because Concord resolves every tracked
|
|
134
|
+
ref itself, so one org-level webhook covers every repo. Route a public HTTPS
|
|
135
|
+
endpoint to the socket with your reverse proxy. If the route breaks, deploys
|
|
136
|
+
are slower, never lost: the interval still runs.
|
|
137
|
+
|
|
138
|
+
## The UI and plan API
|
|
139
|
+
|
|
140
|
+
The daemon also serves a UI and a JSON API on `CONCORD_UI_SOCKET`. **There is
|
|
141
|
+
no authentication.** Route it only on a private network (a VPN, a LAN, an ssh
|
|
142
|
+
tunnel), never publicly. Nothing in it changes production; the only write is
|
|
143
|
+
"plan this branch", which reads.
|
|
144
|
+
|
|
145
|
+
It shows the recent reconciles with their logs, and plans any branch of the
|
|
146
|
+
config on request. **Planning a change**: work on a branch, push it, plan it,
|
|
147
|
+
then merge it. Merging is the deploy.
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
git checkout -b my-change origin/main # in your config repo
|
|
151
|
+
# edit, npm run typecheck, commit
|
|
152
|
+
git push -u origin my-change
|
|
153
|
+
curl -s -X POST 'https://<your UI address>/api/plans?wait=600' \
|
|
154
|
+
-H 'content-type: application/json' \
|
|
155
|
+
-d "{\"branch\": \"my-change\", \"sha\": \"$(git rev-parse HEAD)\"}"
|
|
156
|
+
# read result.modules[].ops, then merge my-change into main
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
- A plan is the whole desired state of the branch, so **a branch behind `main`
|
|
160
|
+
is refused**, because it would show someone else's change being undone.
|
|
161
|
+
Rebase onto `origin/main` and push again.
|
|
162
|
+
- `sha` is optional; when given, the plan is refused unless the branch is at it.
|
|
163
|
+
- `?wait=N` holds the request until the plan finishes (at most 600 s). Without
|
|
164
|
+
it you get the queued plan back at once; poll `GET /api/plans/<id>?wait=N`.
|
|
165
|
+
- Plans run one at a time, in a child `concord plan --no-sync --result` against
|
|
166
|
+
a clone of their own (`$CONCORD_HOME/plans`), never the daemon's checkout.
|
|
167
|
+
|
|
168
|
+
| | |
|
|
169
|
+
|---|---|
|
|
170
|
+
| `GET /api/status` | idle or reconciling, next run, reconciler version and staleness |
|
|
171
|
+
| `GET /api/runs`, `/api/runs/<id>` | recent reconciles; the detail has the log |
|
|
172
|
+
| `POST /api/plans` `{branch, sha?}` | queue a plan (`202`); `400` bad input, `429` queue full |
|
|
173
|
+
| `GET /api/plans`, `/api/plans/<id>` | recent plans; the detail has the changes per module and the log |
|
|
174
|
+
|
|
175
|
+
A plan's `status` is `queued`, `running`, `planned`, `refused` (behind main, no
|
|
176
|
+
such branch, sha mismatch; see `error`) or `failed` (the plan aborted, timed
|
|
177
|
+
out, or crashed). `result.modules[].ops` are the changes; `ahead` is what the
|
|
178
|
+
branch adds over main.
|
|
179
|
+
|
|
180
|
+
## Authoring a config repo
|
|
181
|
+
|
|
182
|
+
A config repo needs this package as a dev dependency (for the types and the
|
|
183
|
+
CLI), TypeScript, and an `age.pub`:
|
|
184
|
+
|
|
185
|
+
```
|
|
186
|
+
git clone <your config repo> && cd <it>
|
|
187
|
+
npm install
|
|
188
|
+
printf '%s' 'value' | npm run secret -- set my-key # with "secret": "concord secret" in package.json
|
|
189
|
+
npm run typecheck
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
`CONCORD_CONFIG_DIR` is unnecessary there: the CLI uses the current directory
|
|
193
|
+
when it contains an `age.pub`. Adding a secret needs only the public key, so
|
|
194
|
+
anyone (or any agent) can author a config without being able to read it.
|
|
195
|
+
|
|
196
|
+
## How the config crosses the boundary
|
|
197
|
+
|
|
198
|
+
The config repo exports **plain data**, not class instances:
|
|
199
|
+
|
|
200
|
+
```ts
|
|
201
|
+
import type { ConcordConfig } from '@rcpooley/concord' // erased at compile time
|
|
202
|
+
import { secrets } from './secrets.js'
|
|
203
|
+
|
|
204
|
+
const hosts = {
|
|
205
|
+
primary: { ip: '127.0.0.1', user: 'deploy', transport: 'local' },
|
|
206
|
+
web1: { ip: '10.0.0.12', user: 'deploy' }, // reached over ssh
|
|
207
|
+
} as const
|
|
208
|
+
|
|
209
|
+
export default {
|
|
210
|
+
schemaVersion: 8,
|
|
211
|
+
hosts,
|
|
212
|
+
modules: [
|
|
213
|
+
{
|
|
214
|
+
type: 'porkbun', id: 'porkbun',
|
|
215
|
+
apiKey: secrets['porkbun-api-key'], secretKey: secrets['porkbun-secret-key'],
|
|
216
|
+
zones: { /* … */ },
|
|
217
|
+
},
|
|
218
|
+
],
|
|
219
|
+
} satisfies ConcordConfig<typeof hosts>
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
`import type` vanishes during compilation, so **the config repo has zero runtime
|
|
223
|
+
dependency on this package**. The reconciler reads inert data, validates it with
|
|
224
|
+
zod, and builds its own module instances via `registry.ts`.
|
|
225
|
+
|
|
226
|
+
That property is load-bearing. An earlier design passed class instances across
|
|
227
|
+
this boundary, which meant the config's copy of the classes had to be forced to
|
|
228
|
+
resolve to the running reconciler via a symlink — and that symlink deleted the
|
|
229
|
+
running code when the CLI was invoked from inside a config checkout, which in
|
|
230
|
+
turn sent `npx` off to execute an unrelated package from the public registry.
|
|
231
|
+
Data across the boundary, instances built here.
|
|
232
|
+
|
|
233
|
+
It also means the resolved config is plain JSON you can dump and inspect.
|
|
234
|
+
|
|
235
|
+
## Two DNS modules, two ownership rules
|
|
236
|
+
|
|
237
|
+
`porkbun` and `cloudflare` diff DNS the same way but disagree about what a zone
|
|
238
|
+
IS, and the difference decides what gets deleted.
|
|
239
|
+
|
|
240
|
+
**`porkbun`** — a declared zone is the whole truth. A live record the config
|
|
241
|
+
does not declare is removed. A zone absent from `zones` is never touched at all.
|
|
242
|
+
|
|
243
|
+
**`cloudflare`** — a declared zone is shared. Every record the module writes
|
|
244
|
+
carries a comment marked `concord:<id>`, and only marked records are ever
|
|
245
|
+
edited or deleted; anything else in the zone is reported once per run and left
|
|
246
|
+
alone. It is the systemd sweeper's rule (`X-Concord=1`) rather than the docker
|
|
247
|
+
sweeper's: the module can only ever remove what it created.
|
|
248
|
+
|
|
249
|
+
That is what lets a human co-own a zone — add a record in the dashboard and
|
|
250
|
+
Concord will not touch it. The cost is that Concord will not adopt one either:
|
|
251
|
+
declaring a record that already exists unowned fails the plan with a message
|
|
252
|
+
naming it, rather than silently taking it over. Delete it in the dashboard, or
|
|
253
|
+
stop declaring it.
|
|
254
|
+
|
|
255
|
+
## Writing a module
|
|
256
|
+
|
|
257
|
+
```ts
|
|
258
|
+
export class MyModule extends Module<MyState, MyOp> {
|
|
259
|
+
readonly kind = 'mymodule'
|
|
260
|
+
async desired(): Promise<MyState> { /* from this.config */ }
|
|
261
|
+
async read(): Promise<MyState> { /* enumerate the live target */ }
|
|
262
|
+
diff(actual, desired): MyOp[] { /* pure, no I/O */ }
|
|
263
|
+
async apply(ops): Promise<void> { /* call the service's API */ }
|
|
264
|
+
}
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
A module declares its config schema **once**, in zod; the TypeScript type is
|
|
268
|
+
inferred from it (`z.infer`), so the author-time type and the runtime validator
|
|
269
|
+
cannot drift. `.strict()` is what rejects unknown keys. Register the class in
|
|
270
|
+
`registry.ts` and add the schema to the union in `schema.ts` — the registry is a
|
|
271
|
+
mapped type over the union, so forgetting one fails to compile.
|
|
272
|
+
|
|
273
|
+
Rules that are not negotiable:
|
|
274
|
+
|
|
275
|
+
- **`read()` is the entry requirement.** A module that cannot enumerate its
|
|
276
|
+
target does not get to be a module. That is what buys plan-before-apply, drift
|
|
277
|
+
detection, and safe adoption.
|
|
278
|
+
- **Every op declares its `kind`** (`create`/`update`/`delete`/`custom`), so the
|
|
279
|
+
runner can count, render, and later gate destructive changes without knowing
|
|
280
|
+
anything about the domain.
|
|
281
|
+
- **`diff()` is pure.** No network calls. It must be safe to run constantly.
|
|
282
|
+
- **Stable instance `id`**, passed to the constructor. Two instances of one
|
|
283
|
+
module have to be distinguishable in plans and logs.
|
|
284
|
+
|
|
285
|
+
### Bringing a module online against existing production
|
|
286
|
+
|
|
287
|
+
1. Implement `read()` and `diff()`. Leave `apply()` throwing `NotImplementedError`.
|
|
288
|
+
2. Run `concord plan` and read the output.
|
|
289
|
+
3. Seed the config from what `read()` returned.
|
|
290
|
+
4. Iterate until **the plan is empty**.
|
|
291
|
+
5. Only then implement `apply()`.
|
|
292
|
+
|
|
293
|
+
An empty plan against untouched production is the acceptance test that the module
|
|
294
|
+
understands reality before it is permitted to change it.
|
|
295
|
+
|
|
296
|
+
## Releasing
|
|
297
|
+
|
|
298
|
+
Releases are manual. `main` can run ahead of the published version, and a
|
|
299
|
+
running daemon only reports itself out of date once a newer version is
|
|
300
|
+
published.
|
|
301
|
+
|
|
302
|
+
```bash
|
|
303
|
+
git checkout main && git pull
|
|
304
|
+
npm version patch # or minor / major; commits the bump and tags it vX.Y.Z
|
|
305
|
+
git push --follow-tags
|
|
306
|
+
npm publish # runs the tests first (prepublishOnly)
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
Bump the **major** version whenever `SCHEMA_VERSION` changes: configs written
|
|
310
|
+
for the old schema are rejected by the new reconciler until they are updated.
|
|
311
|
+
|
|
312
|
+
Then update each daemon when you choose to:
|
|
313
|
+
|
|
314
|
+
```bash
|
|
315
|
+
sudo npm install -g @rcpooley/concord@X.Y.Z
|
|
316
|
+
sudo systemctl restart concord
|
|
317
|
+
```
|
|
318
|
+
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# TEMPLATE for the unit. `concord init` fills in the {{…}} placeholders for
|
|
2
|
+
# the installing user and this install, and writes the result to
|
|
3
|
+
# /etc/systemd/system/concord.service. Concord's own systemd module refuses to
|
|
4
|
+
# manage that file, because whether and when Concord runs must survive a
|
|
5
|
+
# broken config: it is placed once, at install time, never by the config.
|
|
6
|
+
#
|
|
7
|
+
# The daemon owns its own interval, so there is no timer.
|
|
8
|
+
|
|
9
|
+
[Unit]
|
|
10
|
+
Description=Concord — declarative fleet reconciler
|
|
11
|
+
Documentation=https://www.npmjs.com/package/@rcpooley/concord
|
|
12
|
+
After=network-online.target docker.service
|
|
13
|
+
Wants=network-online.target
|
|
14
|
+
|
|
15
|
+
# Retry forever. There is no timer behind this any more, so if systemd ever
|
|
16
|
+
# gave up after the default burst of restarts, nothing would bring Concord
|
|
17
|
+
# back and the fleet would stop reconciling silently. A timer retried forever
|
|
18
|
+
# by construction; this is how that property is preserved.
|
|
19
|
+
StartLimitIntervalSec=0
|
|
20
|
+
|
|
21
|
+
[Service]
|
|
22
|
+
Type=simple
|
|
23
|
+
User={{USER}}
|
|
24
|
+
EnvironmentFile=/etc/concord.env
|
|
25
|
+
|
|
26
|
+
# systemd creates and cleans /run/concord, so the webhook socket has a home
|
|
27
|
+
# that survives nothing and needs no bootstrapping. A reverse proxy in a
|
|
28
|
+
# container should bind-mount this DIRECTORY, never the socket file — a file bind mount would pin the old inode
|
|
29
|
+
# the moment the daemon restarted and recreated it.
|
|
30
|
+
RuntimeDirectory=concord
|
|
31
|
+
RuntimeDirectoryMode=0755
|
|
32
|
+
# Without this, systemd DELETES and recreates /run/concord on every restart —
|
|
33
|
+
# and the proxy's bind mount then points at the old, orphaned directory inode,
|
|
34
|
+
# so every webhook request 502s until the container is recreated. Mounting the
|
|
35
|
+
# directory rather than the socket file is necessary but not sufficient; the
|
|
36
|
+
# directory has to outlive the service too.
|
|
37
|
+
RuntimeDirectoryPreserve=yes
|
|
38
|
+
WorkingDirectory={{HOME}}
|
|
39
|
+
# The node that ran `concord init`, by absolute path: apt, nvm and snap all put
|
|
40
|
+
# it somewhere different. PATH starts with node's own directory so the daemon's
|
|
41
|
+
# children (npm, git) resolve the same way they did for the installing user;
|
|
42
|
+
# systemd's default PATH would miss nvm and /snap/bin.
|
|
43
|
+
Environment=PATH={{PATH}}
|
|
44
|
+
ExecStart={{NODE}} {{DAEMON}}
|
|
45
|
+
|
|
46
|
+
# SIGHUP asks for an immediate reconcile without restarting the process —
|
|
47
|
+
# `systemctl reload concord` is the manual poke that `systemctl start` used
|
|
48
|
+
# to be, and it is the same path the webhook will use.
|
|
49
|
+
ExecReload=/bin/kill -HUP $MAINPID
|
|
50
|
+
|
|
51
|
+
Restart=always
|
|
52
|
+
RestartSec=30
|
|
53
|
+
# A cycle can be a container build. Give it room to finish rather than being
|
|
54
|
+
# killed halfway through an apply.
|
|
55
|
+
TimeoutStopSec=300
|
|
56
|
+
# SIGTERM goes to the daemon ONLY. It finishes the cycle in flight, exits, and
|
|
57
|
+
# only then are leftover children (ssh masters) SIGKILLed. The default,
|
|
58
|
+
# control-group, SIGTERMed every process at once — killing the very deploy the
|
|
59
|
+
# daemon was "finishing". KillMode does not affect
|
|
60
|
+
# `systemctl kill`, which signals the whole cgroup unless given
|
|
61
|
+
# --kill-whom=main: poke with `systemctl reload`, never `systemctl kill`.
|
|
62
|
+
KillMode=mixed
|
|
63
|
+
|
|
64
|
+
# Deliberately NO SyslogIdentifier: setting one detached the daemon's own
|
|
65
|
+
# output from `journalctl -u concord.service`, which is the command anyone
|
|
66
|
+
# actually types. A custom tag is not worth making the logs hard to find.
|
|
67
|
+
|
|
68
|
+
[Install]
|
|
69
|
+
WantedBy=multi-user.target
|
package/dist/age.d.ts
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import type { Secret } from './secret.js';
|
|
2
|
+
/** Generate a fresh age identity. Returns { identity, recipient }. */
|
|
3
|
+
export declare function generateKeypair(): Promise<{
|
|
4
|
+
identity: string;
|
|
5
|
+
recipient: string;
|
|
6
|
+
}>;
|
|
7
|
+
export declare function encryptToRecipient(recipient: string, plaintext: string): Promise<string>;
|
|
8
|
+
/**
|
|
9
|
+
* Decrypts secrets declared in the config repo.
|
|
10
|
+
*
|
|
11
|
+
* FAILS CLOSED: a missing key, a decrypt error, or an empty result is a hard
|
|
12
|
+
* error that aborts the run. A module never applies with a half-resolved
|
|
13
|
+
* secret and never overwrites a good value with an empty one.
|
|
14
|
+
*/
|
|
15
|
+
export declare class SecretResolver {
|
|
16
|
+
#private;
|
|
17
|
+
constructor(identity: string);
|
|
18
|
+
resolve(secret: Secret): Promise<string>;
|
|
19
|
+
}
|
|
20
|
+
//# sourceMappingURL=age.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"age.d.ts","sourceRoot":"","sources":["../src/age.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEzC,sEAAsE;AACtE,wBAAsB,eAAe,IAAI,OAAO,CAAC;IAC/C,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;CAClB,CAAC,CAID;AAED,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,CAAC,CAKjB;AAED;;;;;;GAMG;AACH,qBAAa,cAAc;;gBAIb,QAAQ,EAAE,MAAM;IAWtB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAiC/C"}
|
package/dist/age.js
ADDED
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
import * as age from 'age-encryption';
|
|
2
|
+
/** Generate a fresh age identity. Returns { identity, recipient }. */
|
|
3
|
+
export async function generateKeypair() {
|
|
4
|
+
const identity = await age.generateIdentity();
|
|
5
|
+
const recipient = await age.identityToRecipient(identity);
|
|
6
|
+
return { identity, recipient };
|
|
7
|
+
}
|
|
8
|
+
export async function encryptToRecipient(recipient, plaintext) {
|
|
9
|
+
const e = new age.Encrypter();
|
|
10
|
+
e.addRecipient(recipient);
|
|
11
|
+
const bytes = await e.encrypt(plaintext);
|
|
12
|
+
return Buffer.from(bytes).toString('base64');
|
|
13
|
+
}
|
|
14
|
+
/**
|
|
15
|
+
* Decrypts secrets declared in the config repo.
|
|
16
|
+
*
|
|
17
|
+
* FAILS CLOSED: a missing key, a decrypt error, or an empty result is a hard
|
|
18
|
+
* error that aborts the run. A module never applies with a half-resolved
|
|
19
|
+
* secret and never overwrites a good value with an empty one.
|
|
20
|
+
*/
|
|
21
|
+
export class SecretResolver {
|
|
22
|
+
#decrypter;
|
|
23
|
+
#cache = new Map();
|
|
24
|
+
constructor(identity) {
|
|
25
|
+
const key = identity.trim();
|
|
26
|
+
if (!key) {
|
|
27
|
+
throw new Error('CONCORD_AGE_KEY is empty. Refusing to run — secrets cannot be resolved.');
|
|
28
|
+
}
|
|
29
|
+
this.#decrypter = new age.Decrypter();
|
|
30
|
+
this.#decrypter.addIdentity(key);
|
|
31
|
+
}
|
|
32
|
+
async resolve(secret) {
|
|
33
|
+
const ciphertext = secret;
|
|
34
|
+
const cached = this.#cache.get(ciphertext);
|
|
35
|
+
if (cached !== undefined)
|
|
36
|
+
return cached;
|
|
37
|
+
if (typeof ciphertext !== 'string' || ciphertext.length === 0) {
|
|
38
|
+
throw new Error('Secret reference is empty. Check secrets.ts in the config repo.');
|
|
39
|
+
}
|
|
40
|
+
let plaintext;
|
|
41
|
+
try {
|
|
42
|
+
const bytes = Buffer.from(ciphertext, 'base64');
|
|
43
|
+
plaintext = await this.#decrypter.decrypt(bytes, 'text');
|
|
44
|
+
}
|
|
45
|
+
catch (err) {
|
|
46
|
+
throw new Error(`Failed to decrypt a secret (${ciphertext.slice(0, 12)}…): ` +
|
|
47
|
+
`${err instanceof Error ? err.message : String(err)}. ` +
|
|
48
|
+
`Is CONCORD_AGE_KEY the private half of the config repo's age.pub?`);
|
|
49
|
+
}
|
|
50
|
+
if (plaintext.length === 0) {
|
|
51
|
+
throw new Error(`A secret decrypted to an empty string (${ciphertext.slice(0, 12)}…). ` +
|
|
52
|
+
`Refusing to continue — this is how good values get overwritten with blanks.`);
|
|
53
|
+
}
|
|
54
|
+
this.#cache.set(ciphertext, plaintext);
|
|
55
|
+
return plaintext;
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
//# sourceMappingURL=age.js.map
|
package/dist/age.js.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"age.js","sourceRoot":"","sources":["../src/age.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,gBAAgB,CAAA;AAGrC,sEAAsE;AACtE,MAAM,CAAC,KAAK,UAAU,eAAe;IAInC,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,gBAAgB,EAAE,CAAA;IAC7C,MAAM,SAAS,GAAG,MAAM,GAAG,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAA;IACzD,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAA;AAChC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,SAAiB,EACjB,SAAiB;IAEjB,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,SAAS,EAAE,CAAA;IAC7B,CAAC,CAAC,YAAY,CAAC,SAAS,CAAC,CAAA;IACzB,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;IACxC,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAA;AAC9C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,OAAO,cAAc;IACzB,UAAU,CAAe;IACzB,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAA;IAElC,YAAY,QAAgB;QAC1B,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAA;QAC3B,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,MAAM,IAAI,KAAK,CACb,yEAAyE,CAC1E,CAAA;QACH,CAAC;QACD,IAAI,CAAC,UAAU,GAAG,IAAI,GAAG,CAAC,SAAS,EAAE,CAAA;QACrC,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,GAAG,CAAC,CAAA;IAClC,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,MAAc;QAC1B,MAAM,UAAU,GAAG,MAAgB,CAAA;QACnC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAA;QAC1C,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,MAAM,CAAA;QAEvC,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC9D,MAAM,IAAI,KAAK,CACb,iEAAiE,CAClE,CAAA;QACH,CAAC;QAED,IAAI,SAAiB,CAAA;QACrB,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAA;YAC/C,SAAS,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;QAC1D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,+BAA+B,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM;gBAC1D,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI;gBACvD,mEAAmE,CACtE,CAAA;QACH,CAAC;QAED,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CACb,0CAA0C,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM;gBACrE,6EAA6E,CAChF,CAAA;QACH,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,EAAE,SAAS,CAAC,CAAA;QACtC,OAAO,SAAS,CAAA;IAClB,CAAC;CACF"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":""}
|