Skip to content

Commit 1661e6e

Browse files
arpad-csepiarpad-csepi
committed
docs(dirctl): add daemon configuration documentation
Signed-off-by: Árpád Csepi <csepi.arpad@outlook.com>
1 parent 5ffaa5f commit 1661e6e

1 file changed

Lines changed: 159 additions & 0 deletions

File tree

‎cli/cmd/daemon/README.md‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
# dirctl daemon configuration
2+
3+
The directory daemon (`dirctl daemon start`) runs the gRPC API server and reconciler in one process. Record blobs are stored in an **OCI distribution-compatible registry** configured under `server.store.oci`. The reconciler uses the same registry settings to list tags and run background tasks.
4+
5+
This document describes three ways to supply that registry:
6+
7+
1. **Embedded Zot** — the daemon can start an in-process [Zot](https://zotregistry.io/) server and automatically points the gRPC API server to it.
8+
2. **External registry** — use a hosted registry (for example GitHub Container Registry, ECR, or another cloud OCI service).
9+
3. **Self-hosted / local registry** — use any OCI-compatible registry you run (Zot, distribution, Harbor, and so on) on your machine or network.
10+
11+
## Configuration basics
12+
13+
- **Config file**: Pass `--config /path/to/daemon.config.yaml`. When `--config` is omitted, the daemon loads the embedded reference file `cli/cmd/daemon/daemon.config.yaml` from the binary.
14+
- **Data directory**: `--data-dir` (default when not defined: `~/.agntcy/dir/`). SQLite DB, routing state, keys, and Zot storage paths are resolved relative to this directory unless you use absolute paths.
15+
- **Environment overrides**: Any setting can be overridden with the prefix `DIRECTORY_DAEMON_` (for example `DIRECTORY_DAEMON_SERVER_LISTEN_ADDRESS`). Credentials are often set this way instead of committing them to files:
16+
- `DIRECTORY_DAEMON_SERVER_STORE_OCI_AUTH_CONFIG_USERNAME`
17+
- `DIRECTORY_DAEMON_SERVER_STORE_OCI_AUTH_CONFIG_PASSWORD`
18+
- `DIRECTORY_DAEMON_SERVER_STORE_OCI_AUTH_CONFIG_ACCESS_TOKEN`
19+
- `DIRECTORY_DAEMON_SERVER_STORE_OCI_AUTH_CONFIG_REFRESH_TOKEN`
20+
21+
## Embedded Zot OCI server
22+
23+
When `daemon.zot.enabled` is `true`, the daemon starts Zot before the API server and **overrides** the OCI store to use that instance: registry host/port, repository name from `daemon.zot`, and plain HTTP to the local listener (suitable for single-machine / dev use).
24+
25+
You normally only tune `daemon.zot` and leave `server.store.oci` empty as the daemon sets the effective OCI target at startup.
26+
27+
```yaml
28+
server:
29+
listen_address: "localhost:8888"
30+
store:
31+
provider: "oci"
32+
oci:
33+
# Overridden at runtime when Zot is enabled; shown for clarity only.
34+
verification:
35+
enabled: true
36+
37+
daemon:
38+
zot:
39+
enabled: true
40+
address: "localhost" # HTTP bind address for Zot
41+
port: 5000 # Reference config in the repo uses 5678; viper default if omitted is 5000
42+
repository_name: "dir" # Repository name for storing the OCI artifacts
43+
root_directory: "zot" # Relative path → resolved under <data-dir>
44+
log_level: "warn"
45+
46+
reconciler:
47+
indexer:
48+
enabled: true
49+
# … other reconciler sections as needed
50+
```
51+
52+
**Start:**
53+
54+
```bash
55+
dirctl daemon start --config /path/to/daemon.config.yaml
56+
```
57+
58+
**Notes:**
59+
60+
- Zot readiness is checked on `http://<address>:<port>/v2/` before the API server starts.
61+
- **For production or multi-host setups, prefer an external registry with TLS and auth instead of the embedded server.**
62+
63+
## External registry (hosted OCI)
64+
65+
Set `daemon.zot.enabled` to `false` (can be ommitedas well) and configure `server.store.oci` with the registry hostname (and optional `https://` URL), repository path, TLS behavior, and credentials.
66+
67+
For HTTPS registries, set `auth_config.insecure` to `false` so the client uses `https://` when no scheme is present in `registry_address`.
68+
69+
### Example: GitHub Container Registry (ghcr.io)
70+
71+
```yaml
72+
server:
73+
listen_address: "localhost:8888"
74+
store:
75+
provider: "oci"
76+
oci:
77+
registry_address: "ghcr.io"
78+
repository_name: "my-org/directory-artifacts" # namespace/repo on the registry
79+
auth_config:
80+
insecure: false
81+
username: "my-github-username"
82+
password: "" # Prefer a PAT via DIRECTORY_DAEMON_SERVER_STORE_OCI_AUTH_CONFIG_PASSWORD
83+
84+
daemon:
85+
zot:
86+
enabled: false
87+
88+
reconciler:
89+
indexer:
90+
enabled: true
91+
```
92+
93+
Supply the PAT through the environment:
94+
95+
```bash
96+
export DIRECTORY_DAEMON_SERVER_STORE_OCI_AUTH_CONFIG_PASSWORD="ghp_…"
97+
dirctl daemon start --config /path/to/daemon.config.yaml
98+
```
99+
100+
### Example: generic HTTPS registry with bearer token
101+
102+
```yaml
103+
server:
104+
store:
105+
provider: "oci"
106+
oci:
107+
registry_address: "registry.example.com"
108+
repository_name: "dir/content"
109+
auth_config:
110+
insecure: false
111+
access_token: "" # Use DIRECTORY_DAEMON_SERVER_STORE_OCI_AUTH_CONFIG_ACCESS_TOKEN
112+
```
113+
114+
## Local or self-hosted registry
115+
116+
Use the same `server.store.oci` block with `daemon.zot.enabled: false` (or ommit daemon section). Plain HTTP (typical for `localhost:5000` or a registry in Docker without TLS) should use `auth_config.insecure: true` so the registry URL is treated as `http://…`.
117+
118+
### Example: local distribution / Zot on the same machine
119+
120+
```yaml
121+
server:
122+
listen_address: "localhost:8888"
123+
store:
124+
provider: "oci"
125+
oci:
126+
registry_address: "registry.internal.corp:5000"
127+
repository_name: "directory/blobs"
128+
auth_config:
129+
insecure: true
130+
# Optional if your registry requires auth:
131+
# username: "robot"
132+
# password: "…"
133+
134+
daemon:
135+
zot:
136+
enabled: false
137+
138+
reconciler:
139+
indexer:
140+
enabled: true
141+
```
142+
143+
## Choosing a mode
144+
145+
| Goal | `daemon.zot.enabled` | `server.store.oci` |
146+
| ------------------------------------------------------------- | -------------------- | ------------------------------------------------------ |
147+
| Quickest local dev, no separate registry | `true` | Optional; overridden to embedded Zot |
148+
| Team / CI / production blobs | `false` | Point to your cloud or self-hosted registry |
149+
| You already run Zot or other OCI registry in the same network | `false` | `registry_address` + `repository_name` + `auth_config` |
150+
151+
## Related commands
152+
153+
```bash
154+
dirctl daemon start [--config FILE] [--data-dir DIR]
155+
dirctl daemon status
156+
dirctl daemon stop
157+
```
158+
159+
Client commands such as `dirctl push` talk to the **directory gRPC API** (`server.listen_address`), not directly to the OCI registry; the server persists content to the configured OCI store.

0 commit comments

Comments
 (0)