From b39f6bcff514881fc20d1e373fbb35d3c50a7a7f Mon Sep 17 00:00:00 2001 From: Aiyaret Sandhu Date: Sat, 12 Jul 2025 09:31:07 +0530 Subject: [PATCH 1/2] docs: improve README with setup instructions Signed-off-by: Aiyaret Sandhu --- README.md | 95 +++++++++++++++++++++++++++---------------------------- 1 file changed, 46 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index f0a21d51..c283725e 100644 --- a/README.md +++ b/README.md @@ -44,74 +44,71 @@ The REST API provides an OpenAPI schema that can easily be viewed using the Swag 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/credo-controller.git +cd credo-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. - -> ⚠️ 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. +### Run via Docker -**Directly on Computer** +#### Step 1: Create a Configuration File -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. +In the root directory of the project, create a file named `my-config.json`. +You can base it on the sample located at `/samples/cliConfig.json`. -Once you have installed Indy, you can start the REST server using the following command: +#### Example `my-config.json`: -```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 +```json +{ + "label": "My Credo Agent", + "walletId": "my-wallet", + "walletKey": "my-secret-key", + "walletType": "sqlite", + "walletUrl": "sqlite://wallet.db", + "walletScheme": "ProfilePerWallet", + "walletAccount": "admin", + "walletPassword": "password", + "walletAdminAccount": "admin", + "walletAdminPassword": "admin-password", + "adminPort": 3000, + "walletConnectTimeout": 10000, + "walletMaxConnections": 10, + "walletIdleTimeout": 30000, + "indyLedger": [ + { + "genesisTransactions": "https://raw.githubusercontent.com/bcgov/von-network/main/BCovrin/genesis_test", + "indyNamespace": "bcovrin:testnet" + } + ] +} ``` -**Configuration** +> Ensure `my-config.json` is placed at the root of the project directory. -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. +> Do not commit `my-config.json` to version control. It may contain sensitive credentials. -```sh -# With docker -docker run ghcr.io/hyperledger/afj-rest --help -# Directly on computer -npx -p @aries-framework/rest afj-rest start --help -``` +#### Step 2: Start the Application -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. +Run the following command from the root directory: -```json -{ - "label": "AFJ Rest Agent", - "walletId": "walletId", - "walletKey": "walletKey" - // ... other config options ... // -} +```sh +docker run -p 3000:3000 -v "$(pwd)/my-config.json:/app/my-config.json" ghcr.io/credebl/credo-controller:latest --config /app/my-config.json ``` -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. +This will: + +* Map container port `3000` to your local machine. +* Mount the `my-config.json` configuration file into the container. +* Start the application with the specified configuration. + -```sh -# With docker -docker run -e AFJ_REST_WALLET_KEY=my-secret-key ghcr.io/hyperledger/afj-rest ... -# Directly on computer -AFJ_REST_WALLET_KEY="my-secret-key" npx -p @aries-framework/rest afj-rest start ... -``` #### Starting Own Server @@ -155,7 +152,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 From 73758fad3d508d0d4aeedbae185d5ca585664cea Mon Sep 17 00:00:00 2001 From: Aiyaret Sandhu Date: Thu, 31 Jul 2025 13:54:45 +0530 Subject: [PATCH 2/2] docs: update README with Credo branding and improved setup methods Signed-off-by: Aiyaret Sandhu --- README.md | 181 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 127 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index c283725e..5230000d 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,14 @@


Hyperledger Aries logo

-

Aries Framework JavaScript REST API

+ +# Credo Controller REST API +

- @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 Credo 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 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. > **Note**: The preferred operating system for development and deployment is **Ubuntu LTS (20.04 or later)**. - ### Clone the Repository ```sh @@ -54,79 +54,152 @@ git clone https://github.com/credebl/credo-controller.git cd credo-controller ``` -### Run via Docker +## Getting Started + +### Method 1: Local Development (Recommended for Development) + +
+Local Development Setup + +#### Prerequisites +- Node.js version **18.19.0** (tested and recommended) +- Yarn package manager + +> **Note**: This project requires Node.js 18.19.0. It has been tested and may not work properly with newer versions like Node.js 24.x. + +> **Compatibility**: While Node.js 18.19.0 is recommended, the project should also work with Node.js versions >20 (major versions). However, thorough testing is recommended when using newer Node.js versions. + +#### 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. + +
-#### Step 1: Create a Configuration File +### Method 2: Build and Run Local Docker Image -In the root directory of the project, create a file named `my-config.json`. -You can base it on the sample located at `/samples/cliConfig.json`. +
+Docker Build Instructions -#### Example `my-config.json`: +If you want to build your own Docker image locally and run it: + +#### Steps + +1. **Build the Docker image:** + ```sh + docker build -t credo-controller:local . + ``` + +2. **Run the container:** + ```sh + docker run --network host \ + -v "$(pwd)/samples/cliConfig.json:/app/cliConfig.json" \ + credo-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**. It should work on any system with Docker support. + +
+ +### Method 3: Using Prebuilt Docker Image with PostgreSQL + +
+PostgreSQL + Prebuilt Image Setup + +This method uses the official prebuilt Docker image with a PostgreSQL database setup. + +#### Prerequisites + +First, you need to add these required parameters to `samples/cliConfig.json`: ```json { - "label": "My Credo Agent", - "walletId": "my-wallet", - "walletKey": "my-secret-key", - "walletType": "sqlite", - "walletUrl": "sqlite://wallet.db", - "walletScheme": "ProfilePerWallet", - "walletAccount": "admin", - "walletPassword": "password", - "walletAdminAccount": "admin", - "walletAdminPassword": "admin-password", - "adminPort": 3000, - "walletConnectTimeout": 10000, - "walletMaxConnections": 10, - "walletIdleTimeout": 30000, - "indyLedger": [ - { - "genesisTransactions": "https://raw.githubusercontent.com/bcgov/von-network/main/BCovrin/genesis_test", - "indyNamespace": "bcovrin:testnet" - } - ] + // ...existing configuration... + "walletConnectTimeout": 30, + "walletMaxConnections": 90, + "walletIdleTimeout": 30 + // ...rest of configuration... } ``` -> Ensure `my-config.json` is placed at the root of the project directory. +> **Note**: These parameters are required to avoid wallet connection errors when using PostgreSQL. -> Do not commit `my-config.json` to version control. It may contain sensitive credentials. +#### Steps +1. **Start PostgreSQL database:** + ```sh + docker run --name credo-postgres -d \ + -e POSTGRES_DB=postgres \ + -e POSTGRES_USER=postgres \ + -e POSTGRES_PASSWORD=postgres \ + -p 5432:5432 \ + postgres:13 + ``` -#### Step 2: Start the Application +2. **Run the Credo Controller:** + ```sh + docker run --network host \ + -v "$(pwd)/samples/cliConfig.json:/app/cliConfig.json" \ + ghcr.io/credebl/credo-controller:latest \ + --config /app/cliConfig.json + ``` -Run the following command from the root directory: +This method uses the official prebuilt image and connects to your local PostgreSQL instance. -```sh -docker run -p 3000:3000 -v "$(pwd)/my-config.json:/app/my-config.json" ghcr.io/credebl/credo-controller:latest --config /app/my-config.json -``` +> **OS Compatibility**: This containerized method has been tested and works on **WSL**, **Ubuntu**, and **Fedora**. It should work on any system with Docker support. + +#### Alternative: Using .env File -This will: +The repository includes an agent environment sample file. For a quick start: -* Map container port `3000` to your local machine. -* Mount the `my-config.json` configuration file into the container. -* Start the application with the specified configuration. +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 + ``` +
+## 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 ... // + // ... Credo Config ... // }, agentDependencies ) @@ -137,7 +210,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.