Skip to content

Commit 68417db

Browse files
coodoscoodos
authored
docs: documentation around registry entropy key (#815)
* docs: documentation around registry entropy key * script: add disclaimer * chore: lock * docs: add command in env sample blurb * chore: migration notice
1 parent e8c7503 commit 68417db

5 files changed

Lines changed: 126 additions & 320 deletions

File tree

‎QUICKSTART.md‎

Lines changed: 5 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -1,96 +1,8 @@
1-
# Quick start: registry + evault-core + dev-sandbox
1+
# Quick start
22

3-
Run Postgres and Neo4j in Docker, then start the core services and dev-sandbox with one script.
3+
> [!IMPORTANT]
4+
> THIS DOCUMENTATION HAS BEEN MOVED, PLEASE USE ANY OF THE LINKS BELOW
45
5-
## Prerequisites
6+
**[Local Dev Quick Start Markdown on GitHub](docs/docs/Post%20Platform%20Guide/local-dev-quick-start.md)**
67

7-
- **Docker** (for Postgres and Neo4j)
8-
- **Node.js 18+** and **pnpm**
9-
- **.env** in the repo root (copy from `.env.example` if present, or set the variables below)
10-
11-
## Environment
12-
13-
Create or edit `.env` in the repo root. Minimum for this stack:
14-
15-
```bash
16-
# Postgres (used by registry)
17-
POSTGRES_USER=postgres
18-
POSTGRES_PASSWORD=postgres
19-
REGISTRY_DATABASE_URL=postgresql://postgres:postgres@localhost:5432/registry
20-
21-
# Neo4j (used by evault-core)
22-
NEO4J_USER=neo4j
23-
NEO4J_PASSWORD=your-password
24-
25-
# So the sandbox and evault-core can talk to registry/provisioner
26-
PUBLIC_REGISTRY_URL=http://localhost:4321
27-
PUBLIC_PROVISIONER_URL=http://localhost:3001
28-
REGISTRY_SHARED_SECRET=dev-secret-change-me
29-
PUBLIC_EVAULT_SERVER_URI=http://localhost:4000
30-
```
31-
32-
## One-command start
33-
34-
From the repo root:
35-
36-
```bash
37-
pnpm install
38-
pnpm dev:core
39-
```
40-
41-
Or run steps individually:
42-
43-
```bash
44-
pnpm dev:core:docker
45-
pnpm dev:core:wait
46-
pnpm dev:core:migrate
47-
pnpm dev:core:apps
48-
```
49-
50-
This will:
51-
52-
1. Start **Postgres** (port 5432) and **Neo4j** (7474, 7687) via `docker-compose.databases.yml`
53-
2. Wait for Postgres to be ready
54-
3. Start **registry** (4321), **evault-core** (3001 provisioning, 4000 GraphQL), and **dev-sandbox** (8080) in parallel
55-
56-
Stop with `Ctrl+C`. To stop only the databases: `pnpm docker:core:down`.
57-
58-
## Ports
59-
60-
| Service | Port(s) | Notes |
61-
|----------------|---------|--------------------------|
62-
| Postgres | 5432 | |
63-
| Neo4j HTTP | 7474 | |
64-
| Neo4j Bolt | 7687 | |
65-
| Registry | 4321 | |
66-
| evault-core | 3001, 4000 | Provisioning + GraphQL |
67-
| **Dev sandbox**| **8080**| W3DS dev sandbox UI |
68-
69-
Open **http://localhost:8080** for the dev sandbox (provision, w3ds flows, sign).
70-
71-
## Optional: databases only
72-
73-
To run only Postgres and Neo4j (e.g. you run the app services yourself):
74-
75-
```bash
76-
pnpm docker:core
77-
```
78-
79-
Or: `docker compose -f docker-compose.databases.yml up -d`. Stop with `pnpm docker:core:down`.
80-
81-
## Troubleshooting
82-
83-
**Neo4j "encryption setting" or connection refused:** The stack uses **Neo4j 4.4** (unencrypted Bolt by default). If you previously used Neo4j 5.x, remove the old data and recreate:
84-
85-
```bash
86-
docker compose -f docker-compose.databases.yml down
87-
docker volume rm metastate_neo4j_data 2>/dev/null || true
88-
docker compose -f docker-compose.databases.yml up -d
89-
pnpm dev:core
90-
```
91-
92-
Otherwise ensure `.env` has `NEO4J_URI=bolt://127.0.0.1:7687` and matching `NEO4J_USER` / `NEO4J_PASSWORD`.
93-
94-
---
95-
96-
For full Docker setups and all platform services, see the main [README](README.md).
8+
On the docs site: [docs.w3ds.metastate.foundation](https://docs.w3ds.metastate.foundation/docs/Post%20Platform%20Guide/local-dev-quick-start)

‎docs/docs/Post Platform Guide/local-dev-quick-start.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,9 @@ POSTGRES_USER=postgres
2222
POSTGRES_PASSWORD=postgres
2323
REGISTRY_DATABASE_URL=postgresql://postgres:postgres@localhost:5432/registry
2424

25+
# Registry: ES256 key for signing entropy tokens (required; generate with: pnpm generate-entropy-jwk)
26+
REGISTRY_ENTROPY_KEY_JWK='<paste generated JWK here>'
27+
2528
# Neo4j (used by evault-core)
2629
NEO4J_USER=neo4j
2730
NEO4J_PASSWORD=your-password
@@ -33,6 +36,16 @@ REGISTRY_SHARED_SECRET=dev-secret-change-me
3336
PUBLIC_EVAULT_SERVER_URI=http://localhost:4000
3437
```
3538

39+
### Generating `REGISTRY_ENTROPY_KEY_JWK`
40+
41+
The Registry signs entropy tokens (used by the eID Wallet and provisioning) with an ES256 key. You must set `REGISTRY_ENTROPY_KEY_JWK` to a JSON Web Key (private key). From the repo root, generate a JWK (output to stdout) and add it to `.env`:
42+
43+
```bash
44+
pnpm generate-entropy-jwk
45+
```
46+
47+
Put the output in `.env` as `REGISTRY_ENTROPY_KEY_JWK='<paste>'`. Keep the key private; use the same value across local dev if you need tokens to verify elsewhere.
48+
3649
## One-command start
3750

3851
From the repo root:

‎package.json‎

Lines changed: 58 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -1,59 +1,61 @@
11
{
2-
"name": "prototype",
3-
"private": true,
4-
"scripts": {
5-
"build": "turbo run build",
6-
"dev": "turbo run dev",
7-
"lint": "turbo run lint",
8-
"check-lint": "turbo run check-lint",
9-
"format": "turbo run format",
10-
"check-format": "turbo run check-format",
11-
"check": "turbo run check",
12-
"check-types": "turbo run check-types",
13-
"dev:core": "pnpm dev:core:docker && pnpm dev:core:wait && pnpm dev:core:migrate && pnpm dev:core:apps",
14-
"dev:core:docker": "pnpm docker:core",
15-
"dev:core:wait": "pnpm exec wait-on tcp:127.0.0.1:5432 tcp:127.0.0.1:7687",
16-
"dev:core:migrate": "pnpm --filter registry migration:run && pnpm --filter evault-core build && cross-env REGISTRY_DATABASE_URL= pnpm --filter evault-core migration:run",
17-
"dev:core:apps": "pnpm exec concurrently -n registry,evault,sandbox \"pnpm --filter registry dev\" \"pnpm --filter evault-core dev\" \"pnpm --filter dev-sandbox dev\"",
18-
"docker:core": "docker compose -f docker-compose.databases.yml up -d",
19-
"docker:core:down": "docker compose -f docker-compose.databases.yml down"
20-
},
21-
"devDependencies": {
22-
"@biomejs/biome": "^1.9.4",
23-
"@types/react": "18.3.27",
24-
"@types/react-dom": "18.3.7",
25-
"concurrently": "^9.1.0",
26-
"cross-env": "^7.0.3",
27-
"react": "18.3.1",
28-
"react-dom": "18.3.1",
29-
"turbo": "^2.4.4",
30-
"typescript": "5.8.2",
31-
"wait-on": "^8.0.3"
32-
},
33-
"packageManager": "pnpm@10.25.0",
34-
"engines": {
35-
"node": ">=18"
36-
},
37-
"pnpm": {
38-
"onlyBuiltDependencies": [
39-
"@biomejs/biome",
40-
"@parcel/watcher",
41-
"@rollup/rollup-linux-x64-gnu",
42-
"cpu-features",
43-
"es5-ext",
44-
"esbuild",
45-
"msw",
46-
"protobufjs",
47-
"rollup",
48-
"sqlite3",
49-
"ssh2",
50-
"svelte-preprocess"
51-
],
52-
"overrides": {
53-
"react": "18.3.1",
54-
"react-dom": "18.3.1",
55-
"@types/react": "18.3.27",
56-
"@types/react-dom": "18.3.7"
57-
}
2+
"name": "prototype",
3+
"private": true,
4+
"scripts": {
5+
"build": "turbo run build",
6+
"dev": "turbo run dev",
7+
"lint": "turbo run lint",
8+
"check-lint": "turbo run check-lint",
9+
"format": "turbo run format",
10+
"check-format": "turbo run check-format",
11+
"check": "turbo run check",
12+
"check-types": "turbo run check-types",
13+
"dev:core": "pnpm dev:core:docker && pnpm dev:core:wait && pnpm dev:core:migrate && pnpm dev:core:apps",
14+
"dev:core:docker": "pnpm docker:core",
15+
"dev:core:wait": "pnpm exec wait-on tcp:127.0.0.1:5432 tcp:127.0.0.1:7687",
16+
"dev:core:migrate": "pnpm --filter registry migration:run && pnpm --filter evault-core build && cross-env REGISTRY_DATABASE_URL= pnpm --filter evault-core migration:run",
17+
"dev:core:apps": "pnpm exec concurrently -n registry,evault,sandbox \"pnpm --filter registry dev\" \"pnpm --filter evault-core dev\" \"pnpm --filter dev-sandbox dev\"",
18+
"docker:core": "docker compose -f docker-compose.databases.yml up -d",
19+
"docker:core:down": "docker compose -f docker-compose.databases.yml down",
20+
"generate-entropy-jwk": "node scripts/generate-registry-entropy-jwk.cjs"
21+
},
22+
"devDependencies": {
23+
"@biomejs/biome": "^1.9.4",
24+
"@types/react": "18.3.27",
25+
"@types/react-dom": "18.3.7",
26+
"concurrently": "^9.1.0",
27+
"cross-env": "^7.0.3",
28+
"react": "18.3.1",
29+
"react-dom": "18.3.1",
30+
"turbo": "^2.4.4",
31+
"typescript": "5.8.2",
32+
"wait-on": "^8.0.3",
33+
"jose": "^5.2.2"
34+
},
35+
"packageManager": "pnpm@10.25.0",
36+
"engines": {
37+
"node": ">=18"
38+
},
39+
"pnpm": {
40+
"onlyBuiltDependencies": [
41+
"@biomejs/biome",
42+
"@parcel/watcher",
43+
"@rollup/rollup-linux-x64-gnu",
44+
"cpu-features",
45+
"es5-ext",
46+
"esbuild",
47+
"msw",
48+
"protobufjs",
49+
"rollup",
50+
"sqlite3",
51+
"ssh2",
52+
"svelte-preprocess"
53+
],
54+
"overrides": {
55+
"react": "18.3.1",
56+
"react-dom": "18.3.1",
57+
"@types/react": "18.3.27",
58+
"@types/react-dom": "18.3.7"
5859
}
60+
}
5961
}

0 commit comments

Comments
 (0)