diff --git a/.env.sample b/.env.sample index 46b3a602..6c6cdb4c 100644 --- a/.env.sample +++ b/.env.sample @@ -1,8 +1,14 @@ -# Specify connect timeout +# Wallet connection-pool settings. These map to the wallet-connect-timeout, wallet-max-connections, +# and wallet-idle-timeout CLI options. Prefer the AFJ_REST_WALLET_* variables; the CONNECT_TIMEOUT, +# MAX_CONNECTIONS, and IDLE_TIMEOUT fallbacks are also supported. +# Specify wallet connect timeout +# AFJ_REST_WALLET_CONNECT_TIMEOUT CONNECT_TIMEOUT= -# Specify max connections +# Specify wallet max connections +# AFJ_REST_WALLET_MAX_CONNECTIONS MAX_CONNECTIONS= -# Specify idle timeout +# Specify wallet idle timeout +# AFJ_REST_WALLET_IDLE_TIMEOUT IDLE_TIMEOUT= #Specify max number 2147483647 SESSION_ACQUIRE_TIMEOUT= diff --git a/README.md b/README.md index f0a21d51..f41a7d03 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,17 @@


Hyperledger Aries logo

-

Aries Framework JavaScript REST API

+ +# Agent Controller REST API +

License - @aries-framework/rest version -


-The Aries Framework JavaScript REST API is the most convenient way for self-sovereign identity (SSI) developers to interact with SSI agents. +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 +## 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:3000/docs). +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 Aries Framework JavaScript. 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. +> 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 Using the CLI is the easiest way to get started with the REST API. -**With Docker (easiest)** +> **Note**: The preferred operating system for development and deployment is **Ubuntu LTS (20.04 or later)**. -Make sure you have [Docker](https://docs.docker.com/get-docker/) installed. To get a minimal version of the agent running the following command is sufficient: +### Clone the Repository ```sh -docker run -p 5000:5000 -p 3000:3000 ghcr.io/hyperledger/afj-rest \ - --label "AFJ Rest" \ - --wallet-id "walletId" \ - --wallet-key "walletKey" \ - --endpoint http://localhost:5000 \ - --admin-port 3000 \ - --outbound-transport http \ - --inbound-transport http 5000 +git clone https://github.com/credebl/agent-controller.git +cd agent-controller ``` -See the [docker-compose.yml](https://github.com/hyperledger/aries-framework-javascript-ext/tree/main/docker-compose.yml) file for an example of using the afj-rest image with Docker Compose. +## Getting Started -> ⚠️ The Docker image is not optimized for ARM architectures and won't work on Apple Silicon Macs. See the **Directly on Computer** below on how to run it directly on your computer without Docker. +### Method 1: Local Development (Recommended for Development) -**Directly on Computer** +
+Local Development Setup -To run AFJ REST API directly on your computer you need to have the indy-sdk installed. Follow the Indy [installation steps](https://github.com/hyperledger/aries-framework-javascript/tree/main/docs/libindy) for your platform and verify Indy is installed. +#### Prerequisites -Once you have installed Indy, you can start the REST server using the following command: +- Node.js version **20 (LTS)** (tested and recommended) +- Yarn package manager -```sh -npx -p @aries-framework/rest afj-rest start \ - --label "AFJ Rest" \ - --wallet-id "walletId" \ - --wallet-key "walletKey" \ - --endpoint http://localhost:5000 \ - --admin-port 3000 \ - --outbound-transport http \ - --inbound-transport http 5000 -``` +> **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. -**Configuration** +#### Steps -To find out all available configuration options from the CLI, you can run the CLI command with `--help`. This will print a full list of all available options. +1. **Install dependencies:** -```sh -# With docker -docker run ghcr.io/hyperledger/afj-rest --help + ```sh + yarn install + ``` -# Directly on computer -npx -p @aries-framework/rest afj-rest start --help -``` +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. + +
+ +### Method 2: Build and Run Local Docker Image + +
+Docker Build Instructions + +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 + ``` + +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. + +
+ +### Method 3: Using Prebuilt Docker Image with PostgreSQL + +
+PostgreSQL + Prebuilt Image Setup -It is also possible to configure the REST API using a json config. When providing a lot of configuration options, this is definitely the easiest way to use configure the agent. All properties should use camelCase for the key names. See the example [CLI Config](https://github.com/hyperledger/aries-framework-javascript-ext/tree/main/packages/rest/samples/cliConfig.json) for an detailed example. +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 { - "label": "AFJ Rest Agent", - "walletId": "walletId", - "walletKey": "walletKey" - // ... other config options ... // + "walletConnectTimeout": 30, + "walletMaxConnections": 90, + "walletIdleTimeout": 30 } ``` -As a final option it is possible to configure the agent using environment variables. All properties are prefixed by `AFJ_REST` transformed to UPPER_SNAKE_CASE. +> **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. -```sh -# With docker -docker run -e AFJ_REST_WALLET_KEY=my-secret-key ghcr.io/hyperledger/afj-rest ... +#### Steps -# Directly on computer -AFJ_REST_WALLET_KEY="my-secret-key" npx -p @aries-framework/rest afj-rest start ... -``` +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**. +> +> `--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`. + +
+ +## 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 Own Server +### 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 '@aries-framework/rest' -import { Agent } from '@aries-framework/core' -import { agentDependencies } from '@aries-framework/node' +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. const run = async () => { const agent = new Agent( { - // ... AFJ Config ... // + // ... Agent Config ... // }, - agentDependencies + agentDependencies, ) + await agent.initialize() await startServer(agent, { port: 3000 }) } @@ -140,7 +255,7 @@ const run = async () => { run() ``` -### WebSocket & webhooks +### 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 an library, the WebSocket server and webhook url can be configured in the `startServer` and `setupServer` methods. +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