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 DockerA shell and an editorThe tools required by the release verification procedure

Install Registry Stack

Download one exact rstack-vX.Y.Z-install.sh and the verification material from the same Registry Stack release. Follow the release verification procedure before running the installer. From the verified release directory, install the breg component:

tag="vX.Y.Z"
bash "rstack-${tag}-install.sh" breg
rstack breg --version

The managed installation exposes rstack on your PATH. The breg component supplies the Base Registry Engine runtime and its command-line tools from the same release.

Create a project

mkdir -p tutorial-work
rstack breg 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

rstack breg 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.

registry.yaml

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:

registry.yaml

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

rstack breg 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

rstack breg 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

rstack breg 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

List the contacts as editor. The command finds the running project, gets a fresh short-lived token for that registered local client, and sends the request:

rstack breg api /v1/records/contacts --client editor

{
  "items": [
    {
      "domainData": {
        "email": "contact@example.test",
        "jurisdiction": "zone-a",
        "name": "Example contact"
      },
      "recordIdentifier": "<record-id>",
      "revisionIdentifier": "1"
    }
  ],
  "meta": {
    "datasetIdentifier": "directory",
    "recordTypeIdentifier": "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:

rstack breg api /v1/records/contacts --client foreign-editor

{
  "items": [],
  "meta": {
    "datasetIdentifier": "directory",
    "recordTypeIdentifier": "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 rstack breg dev stop --remove in this directory to stop it and delete its data.

Next

Change a registry with an Action