Create your first registry

In about fifteen minutes you will have a registry running on your machine with one test contact in it, readable by your own staff and hidden from staff elsewhere. You write no code: you create the registry, check it, start it, add the contact, and read it back.

Outcome: A running local registry holding one test contact that only the callers allowed to read it can see.
Time: About 15 minutes, plus image downloads
Level: Local evaluation only
Prerequisites: Running DockercurlA shell and an editor

Install breg and bregctl

breg is the registry server and bregctl the command-line tool you drive it with. The installer checks the release checksums and puts both in ~/.local/bin; keep that directory on your PATH.

curl -fsSL https://github.com/registrystack/registry-stack/releases/latest/download/breg-install.sh | bash
bregctl --version

Create a project

mkdir -p tutorial-work
bregctl init tutorial-work/project
cd tutorial-work/project

Initialized a registry project. 9 artifacts written.
  revision  sha256:<digest>

  README.md
  dev-clients.yaml
  examples/inputs/contact.json
  examples/inputs/email-update.json
  examples/inputs/registration.json
  examples/scenarios.json
  registry.yaml
  runtime.example.yaml
  tests/journeys.yaml

A project is a directory of YAML files that describes one registry. registry.yaml holds what the registry stores and who may read and change it, dev-clients.yaml names two test callers, and examples/ holds ready-made requests. Run the remaining commands from this directory.

Check the project

bregctl check .

Authoring check passed; registry revision sha256:<digest>.
0 errors, 0 warnings in 3 files

Open registry.yaml. It declares one Record type, contact, with three fields. Each contact you store is a Record of that type.

recordTypes:
  - id: contact
    route: contacts
    primaryDataset: directory
    mutationMode: mutable
    display: {label: Contact, description: A named institutional contact.}
    fields:
      - {id: name, type: string, required: true, minimumLength: 1, maximumLength: 160, classification: internal}
      - {id: email, type: string, required: true, minimumLength: 1, maximumLength: 254, classification: internal}
      - {id: jurisdiction, type: string, required: true, minimumLength: 1, maximumLength: 40, classification: internal}

Further down, an access profile says who may read and change contacts. A caller needs the registry:directory:write scope, may create, read, list and change contacts, and only reaches contacts whose jurisdiction equals the jurisdiction claim in its token:

accessProfiles:
  - id: directory-editor
    default: true
    principalClaim: registry_principal
    requiredScopes: ["registry:directory:write"]
    requiredPurposes: [directory-administration]
    permissions:
      records:
        - recordType: contact
          operations: [create, get, list, patch]
          readableFields: [name, email, jurisdiction]
          writableFields: [name, email, jurisdiction]
          rowBoundaries:
            - {field: jurisdiction, claim: jurisdiction, operator: equals}

dev-clients.yaml gives the test caller editor the claim zone-a and foreign-editor the claim zone-b.

Start the registry

bregctl dev start

bregctl dev succeeded.
  status          ready
  project         <project-dir>
  breg url        http://127.0.0.1:<port>
  token endpoint  http://127.0.0.1:<port>/oauth2/token
  audience        urn:breg:dev:<audience>
  package digest  sha256:<digest>
  state file      <project-dir>/.breg/dev/state.json
  runtime config  <project-dir>/.breg/dev/runtime.yaml

  client editor
    client id file      <project-dir>/.breg/dev/credentials/editor/client-id
    assertion key file  <project-dir>/.breg/dev/credentials/editor/assertion-key.jwk

  client foreign-editor
    client id file      <project-dir>/.breg/dev/credentials/foreign-editor/client-id
    assertion key file  <project-dir>/.breg/dev/credentials/foreign-editor/assertion-key.jwk

bregctl started PostgreSQL and a local token issuer in Docker, ran the project’s tests, and started the registry at breg url. The first start downloads the images and takes longer. The files under .breg/dev/ are private keys for the two test callers; keep them out of version control.

If the start reports that a port is in use, another program holds it. Start again with --breg-port, --issuer-port or --database-port set to a free port, and use your breg url in place of http://127.0.0.1:8090 below.

Add a test contact

bregctl examples run contact

bregctl examples run succeeded.
  project   <project-dir>
  scenario  contact
  attempt   <attempt-id>

The contact example in examples/scenarios.json creates one test contact in zone-a as the editor caller and reads it back. The rest of the output shows the registry’s response to each step.

Read the contact as two callers

Get a token for each test caller. Each is valid for five minutes; run the command again when it expires.

bregctl dev token editor
bregctl dev token foreign-editor

bregctl dev token succeeded.
bregctl dev token succeeded.

Each token is saved, ready to send, as an HTTP header in .breg/dev/secrets/. List the contacts as editor:

curl -s -H @.breg/dev/secrets/editor.header http://127.0.0.1:8090/v1/records/contacts

{
  "items": [
    {
      "domainData": {
        "email": "contact@example.test",
        "jurisdiction": "zone-a",
        "name": "Example contact"
      },
      "recordIdentifier": "<record-id>",
      "revisionIdentifier": "1"
    }
  ],
  "meta": {
    "datasetIdentifier": "directory",
    "entityTypeIdentifier": "contact",
    "registryIdentifier": "local-directory"
  },
  "pageInfo": {
    "nextCursor": null
  }
}

The Record carries a stable identifier and a revision number beside the fields. Now list the same contacts as foreign-editor, whose token says zone-b:

curl -s -H @.breg/dev/secrets/foreign-editor.header http://127.0.0.1:8090/v1/records/contacts

{
  "items": [],
  "meta": {
    "datasetIdentifier": "directory",
    "entityTypeIdentifier": "contact",
    "registryIdentifier": "local-directory"
  },
  "pageInfo": {
    "nextCursor": null
  }
}

The registry applied the access profile: the contact exists, and foreign-editor cannot see it.

Leave the registry running

The next tutorial continues with this registry and its contact, so leave it running. When you are finished with it, run bregctl dev stop --remove in this directory to stop it and delete its data.

Change a registry with an Action