From e5303cc258ca63e9eb8bf543d52d89bd8bd515c1 Mon Sep 17 00:00:00 2001 From: Catarina Paralta Date: Thu, 29 Jan 2026 10:27:32 +0000 Subject: [PATCH 1/4] docs: extend storage documentation with multi registry support and configuration details Signed-off-by: Catarina Paralta --- docs/dir/scenarios.md | 83 +++++++++++++++++++++++++++++++++++++++---- 1 file changed, 76 insertions(+), 7 deletions(-) diff --git a/docs/dir/scenarios.md b/docs/dir/scenarios.md index 9848867..93489d9 100644 --- a/docs/dir/scenarios.md +++ b/docs/dir/scenarios.md @@ -58,13 +58,82 @@ EOF ## Store -This example demonstrates the interaction with the local storage layer using the CLI client. -The storage layer uses an OCI-compliant registry (powered by [Zot](https://github.com/project-zot/zot)) to store records as OCI -artifacts with [content-addressable identifiers](https://github.com/multiformats/cid) (CIDs). -When a record is pushed, it is stored as an OCI blob and the CID is calculated by converting -the SHA256 OCI digest into a CIDv1 format using CID multihash encoding. Each record is then -tagged with its CID in the registry, enabling direct lookup and ensuring content -integrity through cryptographic addressing. +This example demonstrates the interaction with the storage layer using the CLI client. +The storage layer uses an OCI-compliant registry to store records as OCI artifacts with +[content-addressable identifiers](https://github.com/multiformats/cid) (CIDs). When a record +is pushed, it is stored as an OCI blob and the CID is calculated by converting the SHA256 +OCI digest into a CIDv1 format using CID multihash encoding. Each record is then tagged with +its CID in the registry, enabling direct lookup and ensuring content integrity through +cryptographic addressing. + +### Supported Registries + +The Directory supports multiple OCI-compatible registry backends: + +| Registry Type | Description | +|---------------|-------------| +| `zot` | [Zot](https://github.com/project-zot/zot) OCI registry (default) | +| `ghcr` | GitHub Container Registry | +| `dockerhub` | Docker Hub | + +### Registry Configuration + +The registry backend is configured via environment variables on the Directory server: + +| Environment Variable | Description | Default | +|---------------------|-------------|---------| +| `DIRECTORY_SERVER_STORE_OCI_TYPE` | Registry type (`zot`, `ghcr`, `dockerhub`) | `zot` | +| `DIRECTORY_SERVER_STORE_OCI_REGISTRY_ADDRESS` | Registry address | `127.0.0.1:5000` | +| `DIRECTORY_SERVER_STORE_OCI_REPOSITORY_NAME` | Repository name | `dir` | + +### Authentication Configuration + +Credentials for the registry are configured via environment variables: + +| Environment Variable | Description | +|---------------------|-------------| +| `DIRECTORY_SERVER_STORE_OCI_AUTH_CONFIG_USERNAME` | Username for basic authentication | +| `DIRECTORY_SERVER_STORE_OCI_AUTH_CONFIG_PASSWORD` | Password for basic authentication | +| `DIRECTORY_SERVER_STORE_OCI_AUTH_CONFIG_ACCESS_TOKEN` | Access token for token-based authentication | +| `DIRECTORY_SERVER_STORE_OCI_AUTH_CONFIG_INSECURE` | Skip TLS verification (default: `true`) | + +### Configuration Examples + +**Zot (Local Development)** + +```bash +export DIRECTORY_SERVER_STORE_OCI_TYPE=zot +export DIRECTORY_SERVER_STORE_OCI_REGISTRY_ADDRESS=localhost:5000 +export DIRECTORY_SERVER_STORE_OCI_REPOSITORY_NAME=dir +export DIRECTORY_SERVER_STORE_OCI_AUTH_CONFIG_INSECURE=true +``` + +**GitHub Container Registry (GHCR)** + +```bash +export DIRECTORY_SERVER_STORE_OCI_TYPE=ghcr +export DIRECTORY_SERVER_STORE_OCI_REGISTRY_ADDRESS=ghcr.io +export DIRECTORY_SERVER_STORE_OCI_REPOSITORY_NAME=your-org/dir +export DIRECTORY_SERVER_STORE_OCI_AUTH_CONFIG_USERNAME=your-github-username +export DIRECTORY_SERVER_STORE_OCI_AUTH_CONFIG_PASSWORD=your-github-token +export DIRECTORY_SERVER_STORE_OCI_AUTH_CONFIG_INSECURE=false +``` + +**Docker Hub** + +```bash +export DIRECTORY_SERVER_STORE_OCI_TYPE=dockerhub +export DIRECTORY_SERVER_STORE_OCI_REGISTRY_ADDRESS=docker.io +export DIRECTORY_SERVER_STORE_OCI_REPOSITORY_NAME=your-username/dir +export DIRECTORY_SERVER_STORE_OCI_AUTH_CONFIG_USERNAME=your-dockerhub-username +export DIRECTORY_SERVER_STORE_OCI_AUTH_CONFIG_PASSWORD=your-dockerhub-token +export DIRECTORY_SERVER_STORE_OCI_AUTH_CONFIG_INSECURE=false +``` + +### Basic Operations + +Once the server is configured, the CLI operations work the same regardless of the underlying +registry backend: ```bash # Push the record and store its CID to a file From d0de1975011a324a023318e46fce1dcc7b5a3f2c Mon Sep 17 00:00:00 2001 From: Catarina Paralta Date: Thu, 29 Jan 2026 10:34:20 +0000 Subject: [PATCH 2/4] docs: add synchronization requirements for non-Zot registries in scenarios.md Signed-off-by: Catarina Paralta --- docs/dir/scenarios.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/dir/scenarios.md b/docs/dir/scenarios.md index 93489d9..c525b95 100644 --- a/docs/dir/scenarios.md +++ b/docs/dir/scenarios.md @@ -76,6 +76,13 @@ The Directory supports multiple OCI-compatible registry backends: | `ghcr` | GitHub Container Registry | | `dockerhub` | Docker Hub | +!!! warning "Synchronization Requirements for Non-Zot Registries" + Synchronization between non-Zot registries (GHCR, DockerHub) requires PostgreSQL as + the database backend, the reconciler component enabled, and the regsync task enabled + (`RECONCILER_REGSYNC_ENABLED=true`). The reconciler uses + [regsync](https://github.com/regclient/regclient) to handle cross-registry + synchronization when either the local or remote registry is not Zot. + ### Registry Configuration The registry backend is configured via environment variables on the Directory server: From 1f185ee2cf46152a3c62be0b14632b5d40e31c46 Mon Sep 17 00:00:00 2001 From: Aron Kerekes Date: Thu, 29 Jan 2026 12:42:48 +0100 Subject: [PATCH 3/4] chore: list formating Signed-off-by: Aron Kerekes --- docs/dir/scenarios.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/dir/scenarios.md b/docs/dir/scenarios.md index c525b95..bf7b3bb 100644 --- a/docs/dir/scenarios.md +++ b/docs/dir/scenarios.md @@ -76,12 +76,15 @@ The Directory supports multiple OCI-compatible registry backends: | `ghcr` | GitHub Container Registry | | `dockerhub` | Docker Hub | -!!! warning "Synchronization Requirements for Non-Zot Registries" - Synchronization between non-Zot registries (GHCR, DockerHub) requires PostgreSQL as - the database backend, the reconciler component enabled, and the regsync task enabled - (`RECONCILER_REGSYNC_ENABLED=true`). The reconciler uses - [regsync](https://github.com/regclient/regclient) to handle cross-registry - synchronization when either the local or remote registry is not Zot. +#### Synchronization Requirements for Non-Zot Registries + +Synchronization between non-Zot registries (GHCR, DockerHub) requires the following: + +- PostgreSQL as the database backend +- The reconciler component enabled +- The regsync task enabled (`RECONCILER_REGSYNC_ENABLED=true`) + +The reconciler uses [regsync](https://github.com/regclient/regclient) to handle cross-registry synchronization when either the local or remote registry is not Zot. ### Registry Configuration From b8452c512b2f32cf1dbe8a3c0e5b8fb353bd1ebe Mon Sep 17 00:00:00 2001 From: Catarina Paralta Date: Thu, 29 Jan 2026 12:27:50 +0000 Subject: [PATCH 4/4] docs: remove no longer supported list wildcard search Signed-off-by: Catarina Paralta --- docs/dir/scenarios.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/docs/dir/scenarios.md b/docs/dir/scenarios.md index bf7b3bb..7ddec3a 100644 --- a/docs/dir/scenarios.md +++ b/docs/dir/scenarios.md @@ -391,16 +391,9 @@ dirctl search --version "v1.0.?" # Find version v1.0.x (single dig dirctl search --name "???api" # Find 3-character names ending in "api" dirctl search --skill "Pytho?" # Find skills with single character variations -# List wildcards ([]) - matches any character within brackets -dirctl search --name "agent-[0-9]" # Find agents with numeric suffixes -dirctl search --version "v[0-9].*" # Find versions starting with v + digit -dirctl search --skill "[a-m]*" # Find skills starting with a-m -dirctl search --locator "[hf]tt[ps]*" # Find HTTP/HTTPS/FTP locators - # Complex wildcard combinations dirctl search --name "api-*-service" --version "v2.*" dirctl search --skill "*machine*learning*" -dirctl search --name "web-[0-9]?" --version "v?.*.?" ``` **Available Search Flags:**