Skip to content

Getting Started

This guide will help you get started with the Directory project, including setting up your development environment, building the project, running tests, and deploying the services.

Prerequisites

To build the project and work with the code, you need the following components installed in your system:

Note

Make sure Docker is installed with Buildx.

Quick Start

To quickly get started with the Directory project, you need two components:

  • Directory API Server: The main service that manages agent directory records and handles API requests. Check Deployment section for deployment options.
  • Directory Client: A command-line or SDK tool to interact with the Directory API Server. Check Artifacts distribution section for installation instructions.

Development

Use Taskfile for all related development operations such as testing, validating, deploying, and working with the project.

Clone the repository

git clone https://github.com/agntcy/dir
cd dir

Initialize the project

This step fetches all project dependencies and prepares the environment for development.

task deps

Make changes

Make the changes to the source code and rebuild for later testing.

task build

Test changes

The local testing pipeline relies on Golang to perform unit tests, and Docker to perform E2E tests in an isolated Kubernetes environment using Kind.

task test:unit
task test:e2e

Artifacts distribution

All artifacts are tagged using the Semantic Versioning and follow the checked-out source code tags. It is not advised to use artifacts with mismatched versions.

Container images

All container images are distributed via GitHub Packages.

docker pull ghcr.io/agntcy/dir-ctl:v0.3.0
docker pull ghcr.io/agntcy/dir-apiserver:v0.3.0

Helm charts

All helm charts are distributed as OCI artifacts via GitHub Packages.

helm pull oci://ghcr.io/agntcy/dir/helm-charts/dir --version v0.3.0

Binaries

All release binaries are distributed via GitHub Releases and Homebrew agntcy/dir tap.

Check CLI References for detailed installation instructions.

SDKs

Deployment

Directory API services can be deployed either using the Taskfile or directly via the released Helm chart.

Using Taskfile

This starts the necessary components such as storage and API services.

task server:start

Using Helm chart

This deploys Directory services into an existing Kubernetes cluster.

helm pull oci://ghcr.io/agntcy/dir/helm-charts/dir --version v0.3.0
helm upgrade --install dir oci://ghcr.io/agntcy/dir/helm-charts/dir --version v0.3.0

Using Docker Compose

This deploys Directory services using Docker Compose:

cd install/docker
docker compose up -d