docs: improve README with setup instructions #288
+191
−70
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,15 +1,17 @@ | ||
| <p align="center"> | ||
| <br /> | ||
| <img | ||
| alt="CREDEBL logo" | ||
| src="https://raw.githubusercontent.com/credebl/.github/main/logo.svg" | ||
| height="150px" | ||
| /> | ||
| </p> | ||
|
|
||
| # Agent Controller REST API | ||
|
|
||
| <p align="center"> | ||
| <a | ||
| href="https://raw.githubusercontent.com/credebl/agent-controller/main/LICENSE" | ||
| ><img | ||
| alt="License" | ||
| src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" | ||
|
|
@@ -19,128 +21,241 @@ | |
| alt="typescript" | ||
| src="https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg" | ||
| /></a> | ||
| <a href="https://github.com/credebl/agent-controller" | ||
| ><img | ||
| alt="GitHub" | ||
| src="https://img.shields.io/github/stars/credebl/agent-controller?style=social" | ||
| /></a> | ||
| </p> | ||
| <br /> | ||
|
|
||
| The Agent Controller REST API is the most convenient way for self-sovereign identity (SSI) developers to interact with SSI agents. | ||
|
|
||
| - ⭐ **Endpoints** to create connections, issue credentials, and request proofs. | ||
| - 💻 **CLI** that makes it super easy to start an instance of the REST API. | ||
| - 🌐 **Interoperable** with all major Aries implementations. | ||
|
|
||
| ## Quick Start | ||
|
|
||
| The REST API provides an OpenAPI schema that can easily be viewed using the SwaggerUI that is provided with the server. The docs can be viewed on the `/docs` endpoint (e.g. http://localhost:4001/docs, where `4001` is the admin port configured in `samples/cliConfig.json`). | ||
|
|
||
| > The OpenAPI spec is generated from the model classes used by Credo-TS. Due to limitations in the inspection of these classes, the generated schema does not always exactly match the expected format. Keep this in mind when using this package. If you encounter any issues, feel free to open an issue. | ||
|
|
||
| ### Using the CLI | ||
|
|
||
| Using the CLI is the easiest way to get started with the REST API. | ||
|
|
||
| > **Note**: The preferred operating system for development and deployment is **Ubuntu LTS (20.04 or later)**. | ||
|
There was a problem hiding this comment. 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -eu
printf '%s\n' '--- README context ---'
sed -n '40,54p' README.md
printf '%s\n' '--- repository references to Ubuntu support ---'
rg -n -i 'ubuntu|20\.04|22\.04|24\.04|operating system' README.md .github 2>/dev/null || trueRepository: credebl/agent-controller Length of output: 1647 🌐 Web query:
💡 Result: Ubuntu 20.04 LTS (Focal Fossa) reached the end of its standard security maintenance period on May 31, 2025 [1][2][3]. Current Support Status: As of today, August 13, 2026, Ubuntu 20.04 LTS is no longer receiving standard security updates [4][3]. Systems running this version are now reliant on Extended Security Maintenance (ESM), which is available through an Ubuntu Pro subscription [2][5][6]. With an active Ubuntu Pro subscription, security maintenance for Ubuntu 20.04 LTS is extended until April 2030, with an additional option for Legacy Support to extend coverage until April 2032 [2][7][6]. Ubuntu Release Cycle Overview: Ubuntu follows a strict time-based release cycle, with new versions published every six months [8]. Long Term Support (LTS) releases occur every two years (in April of even-numbered years) and are the only releases that receive extended maintenance commitments [8]. - Standard Support: LTS releases receive five years of standard security maintenance for packages in the 'main' repository [2][8]. - Extended Security Maintenance (ESM): Following the end of standard support, ESM provides continued security updates through Ubuntu Pro for both 'main' and 'universe' repository packages [7][5][8]. Citations:
Raise the minimum supported Ubuntu release. Ubuntu 20.04 is no longer under standard security maintenance. Set the minimum to an actively supported LTS, or require Ubuntu Pro/ESM for Ubuntu 20.04. Align 🤖 Prompt for AI AgentsSource: MCP tools |
||
|
|
||
| ### Clone the Repository | ||
|
|
||
| ```sh | ||
| git clone https://github.com/credebl/agent-controller.git | ||
| cd agent-controller | ||
| ``` | ||
|
|
||
| ## Getting Started | ||
|
|
||
| ### Method 1: Local Development (Recommended for Development) | ||
|
|
||
| <details> | ||
| <summary><strong>Local Development Setup</strong></summary> | ||
|
|
||
| #### Prerequisites | ||
|
|
||
| - Node.js version **20 (LTS)** (tested and recommended) | ||
| - Yarn package manager | ||
|
|
||
| > **Note**: Node.js 20 (LTS) is used in CI and is the recommended version. The Docker image builds and runs on Node.js 22, so newer LTS versions should also work, but thorough testing is recommended before using them. | ||
|
|
||
| #### Steps | ||
|
|
||
| 1. **Install dependencies:** | ||
|
|
||
| ```sh | ||
| yarn install | ||
| ``` | ||
|
|
||
| 2. **Build the project:** | ||
|
|
||
| ```sh | ||
| yarn build | ||
| ``` | ||
|
|
||
| 3. **Start development server:** | ||
| ```sh | ||
| yarn dev | ||
| ``` | ||
|
|
||
| The application will start in development mode with hot reloading enabled. | ||
|
|
||
| </details> | ||
|
|
||
| ### Method 2: Build and Run Local Docker Image | ||
|
|
||
| <details> | ||
| <summary><strong>Docker Build Instructions</strong></summary> | ||
|
|
||
| If you want to build your own Docker image locally and run it: | ||
|
|
||
| #### Steps | ||
|
|
||
| 1. **Build the Docker image:** | ||
|
|
||
| ```sh | ||
| docker build -t agent-controller:local . | ||
| ``` | ||
|
|
||
| 2. **Run the container:** | ||
| ```sh | ||
| docker run --network host \ | ||
| -v "$(pwd)/samples/cliConfig.json:/app/cliConfig.json" \ | ||
| agent-controller:local --config /app/cliConfig.json | ||
| ``` | ||
|
Comment on lines
+111
to
+114
There was a problem hiding this comment. 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -eu
printf '%s\n' '--- README.md lines 90-180 ---'
sed -n '90,180p' README.md
printf '%s\n' '--- README.md lines 200-285 ---'
sed -n '200,285p' README.md
printf '%s\n' '--- samples/cliConfig.json ---'
cat samples/cliConfig.json
printf '%s\n' '--- PostgreSQL-related repository references ---'
rg -n -i 'postgres|5432|cliConfig|fileServerToken|PolygonModule' README.md samples package.json docker-compose.yml .github 2>/dev/null || trueRepository: credebl/agent-controller Length of output: 11502 🏁 Script executed: #!/bin/bash
set -eu
python3 - <<'PY'
import json
from pathlib import Path
config = json.loads(Path("samples/cliConfig.json").read_text())
print({
"walletType": config.get("walletType"),
"walletUrl": config.get("walletUrl"),
"walletAccount": config.get("walletAccount"),
"walletAdminAccount": config.get("walletAdminAccount"),
})
PY
printf '%s\n' '--- Docker build/runtime files ---'
git ls-files | grep -E '(^|/)(Dockerfile[^/]*|docker-compose\.yml)$' | while IFS= read -r file; do
printf '%s\n' "--- $file ---"
cat "$file"
doneRepository: credebl/agent-controller Length of output: 1590 Add PostgreSQL setup to Method 2.
🤖 Prompt for AI AgentsSource: MCP tools |
||
|
|
||
| This method gives you full control over the Docker build process and allows you to customize the image as needed. | ||
|
|
||
| > **OS Compatibility**: This containerized method has been tested and works on **WSL**, **Ubuntu**, and **Fedora**. | ||
| > | ||
| > `--network host` is Linux-only. On **macOS / Windows (Docker Desktop)** use port mapping instead: | ||
| > | ||
| > ```sh | ||
| > docker run -p 4001:4001 -p 4002:4002 \ | ||
| > -v "$(pwd)/samples/cliConfig.json:/app/cliConfig.json" \ | ||
| > agent-controller:local --config /app/cliConfig.json | ||
| > ``` | ||
| > | ||
| > When using port mapping, set `walletUrl` to `host.docker.internal:5432` in the config so the container can reach a PostgreSQL instance running on your host. | ||
|
|
||
| </details> | ||
|
|
||
| ### Method 3: Using Prebuilt Docker Image with PostgreSQL | ||
|
|
||
| <details> | ||
| <summary><strong>PostgreSQL + Prebuilt Image Setup</strong></summary> | ||
|
|
||
| This method uses the official prebuilt Docker image with a PostgreSQL database setup. | ||
|
|
||
| #### Prerequisites | ||
|
|
||
| The `samples/cliConfig.json` file must reference a PostgreSQL wallet (it already uses `walletType: "postgres"`). Optionally, you can tune the connection pool by adding these settings: | ||
|
|
||
| ```json | ||
| { | ||
| "walletConnectTimeout": 30, | ||
| "walletMaxConnections": 90, | ||
| "walletIdleTimeout": 30 | ||
| } | ||
| ``` | ||
|
|
||
| > **Note**: These settings are optional connection-pool tunables for the PostgreSQL wallet. They map to the `wallet-connect-timeout`, `wallet-max-connections`, and `wallet-idle-timeout` CLI options, the `AFJ_REST_WALLET_CONNECT_TIMEOUT`, `AFJ_REST_WALLET_MAX_CONNECTIONS`, and `AFJ_REST_WALLET_IDLE_TIMEOUT` environment variables, or the `CONNECT_TIMEOUT`, `MAX_CONNECTIONS`, and `IDLE_TIMEOUT` environment-variable fallbacks. They are not required for the agent to start. | ||
|
|
||
| #### Steps | ||
|
|
||
| 1. **Start PostgreSQL database:** | ||
|
|
||
| ```sh | ||
| docker run --name agent-controller-postgres -d \ | ||
| -e POSTGRES_DB=postgres \ | ||
| -e POSTGRES_USER=postgres \ | ||
| -e POSTGRES_PASSWORD=postgres \ | ||
| -p 5432:5432 \ | ||
| postgres:16 | ||
| ``` | ||
|
|
||
| 2. **Run the Agent Controller:** | ||
| ```sh | ||
| docker run --network host \ | ||
| -v "$(pwd)/samples/cliConfig.json:/app/cliConfig.json" \ | ||
| ghcr.io/credebl/credo-controller:latest \ | ||
| --config /app/cliConfig.json | ||
| ``` | ||
|
|
||
| This method uses the official prebuilt image and connects to your local PostgreSQL instance. | ||
|
|
||
| > **Note**: The Docker image is still published under the legacy name `ghcr.io/credebl/credo-controller`. The prebuilt image and `docker compose` entry points have not yet been renamed to match the new "Agent Controller" project name. | ||
| > | ||
| > **OS Compatibility**: This containerized method has been tested and works on **WSL**, **Ubuntu**, and **Fedora**. | ||
|
Comment on lines
+176
to
+178
There was a problem hiding this comment. 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win Remove the blank line inside the blockquote. Remove the empty quoted line at Line 177 or keep the entire note in one continuous blockquote. Static analysis reports MD028 for this block. 🧰 Tools🪛 markdownlint-cli2 (0.23.2)[warning] 177-177: Blank line inside blockquote (MD028, no-blanks-blockquote) 🤖 Prompt for AI AgentsSource: Linters/SAST tools |
||
| > | ||
| > `--network host` is Linux-only. On **macOS / Windows (Docker Desktop)** use port mapping instead: | ||
| > | ||
| > ```sh | ||
| > docker run -p 4001:4001 -p 4002:4002 \ | ||
| > -v "$(pwd)/samples/cliConfig.json:/app/cliConfig.json" \ | ||
| > ghcr.io/credebl/credo-controller:latest \ | ||
| > --config /app/cliConfig.json | ||
| > ``` | ||
| > | ||
| > When using port mapping, set `walletUrl` to `host.docker.internal:5432` in the config so the container can reach the PostgreSQL instance running on your host. | ||
|
|
||
| #### Alternative: Using .env File | ||
|
|
||
| The repository includes an agent environment sample file. For a quick start: | ||
|
|
||
| 1. **Rename the sample environment file:** | ||
|
|
||
| ```sh | ||
| cp .env.sample .env # (if available in the repository) | ||
| ``` | ||
|
|
||
| 2. **Run using the binary directly:** | ||
| ```sh | ||
| yarn build | ||
| ./bin/afj-rest.js --config ./samples/cliConfig.json | ||
| ``` | ||
|
|
||
| > **Note**: `afj-rest.js` is the legacy binary name, kept for backward compatibility. The CLI entrypoint is defined in the `bin` field of `package.json`. | ||
|
|
||
| </details> | ||
|
|
||
| ## Configuration | ||
|
|
||
| The agent can be configured in three ways: | ||
|
|
||
| 1. **CLI options**: Run the CLI with `--help` to print the full list of available options. | ||
|
|
||
| ```sh | ||
| # With Docker | ||
| docker run ghcr.io/credebl/credo-controller:latest --help | ||
|
|
||
| # Directly on computer | ||
| ./bin/afj-rest.js start --help | ||
| ``` | ||
|
|
||
| 2. **JSON config file**: When providing a lot of configuration options, pass a JSON file with `--config`. All properties should use camelCase for the key names. See [samples/cliConfig.json](samples/cliConfig.json) for a complete example. | ||
| 3. **Environment variables**: All properties are prefixed with `AFJ_REST` and use UPPER_SNAKE_CASE (e.g. `AFJ_REST_WALLET_KEY=my-secret-key ./bin/afj-rest.js start ...`). | ||
|
|
||
| ## Development | ||
|
|
||
| ### Starting Your Own Server | ||
|
|
||
| Starting your own server is more involved than using the CLI, but allows more fine-grained control over the settings and allows you to extend the REST API with custom endpoints. | ||
|
|
||
| You can create an agent instance and import the `startServer` method from the `rest` package. That's all you have to do. | ||
|
|
||
| ```ts | ||
| import { startServer } from '@credo-ts/rest' | ||
| import { Agent } from '@credo-ts/core' | ||
| import { agentDependencies } from '@credo-ts/node' | ||
|
|
||
| // The startServer function requires an initialized agent and a port. | ||
| // An example of how to setup an agent is located in the `samples` directory. | ||
|
coderabbitai[bot] marked this conversation as resolved.
|
||
| const run = async () => { | ||
| const agent = new Agent( | ||
| { | ||
| // ... Agent Config ... // | ||
| }, | ||
| agentDependencies, | ||
| ) | ||
| await agent.initialize() | ||
| await startServer(agent, { port: 3000 }) | ||
| } | ||
|
|
||
| // A Swagger (OpenAPI) definition is exposed on http://localhost:3000/docs | ||
| run() | ||
| ``` | ||
|
|
||
| ### WebSocket & Webhooks | ||
|
|
||
| The REST API provides the option to connect as a client and receive events emitted from your agent using WebSocket and webhooks. | ||
|
|
||
|
|
@@ -155,7 +270,7 @@ The currently supported events are: | |
|
|
||
| When using the CLI, a webhook url can be specified using the `--webhook-url` config option. | ||
|
|
||
| When using the REST server as a library, the WebSocket server and webhook url can be configured in the `startServer` and `setupServer` methods. | ||
|
|
||
| ```ts | ||
| // You can either call startServer() or setupServer() and pass the ServerConfig interface with a webhookUrl and/or a WebSocket server | ||
|
|
||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.