Skip to content

docs: improve README with setup instructions #288

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Aiyaret-Sandhu wants to merge 2 commits into
base: main
Choose a base branch
from
+133 −63
Open

docs: improve README with setup instructions #288

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b39f6bc
docs: improve README with setup instructions
Aiyaret-Sandhu Jul 12, 2025
73758fa
docs: update README with Credo branding and improved setup methods
Aiyaret-Sandhu Jul 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
196 changes: 133 additions & 63 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,14 @@
<p align="center">
<br />
<img
alt="Hyperledger Aries logo"
src="https://raw.githubusercontent.com/hyperledger/aries-framework-javascript/aa31131825e3331dc93694bc58414d955dcb1129/images/aries-logo.png"
alt="Credo logo"
src="https://raw.githubusercontent.com/openwallet-foundation/credo-ts/main/images/credo-logo.png"
height="250px"
/>
</p>
<h1 align="center"><b>Aries Framework JavaScript REST API</b></h1>

# Credo Controller REST API

<p align="center">
<a
href="https://raw.githubusercontent.com/hyperledger/aries-framework-javascript-ext/main/LICENSE"
Expand All @@ -19,117 +21,185 @@
alt="typescript"
src="https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg"
/></a>
<a href="https://www.npmjs.com/package/@aries-framework/rest"
<a href="https://github.com/credebl/credo-controller"
><img
alt="@aries-framework/rest version"
src="https://img.shields.io/npm/v/@aries-framework/rest"
alt="GitHub"
src="https://img.shields.io/github/stars/credebl/credo-controller?style=social"
/></a>

</p>
<br />

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.

**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.
## 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**
<details>
<summary><strong>Local Development Setup</strong></summary>

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
- Node.js version **18.19.0** (tested and recommended)
- Yarn package manager

Once you have installed Indy, you can start the REST server using the following command:
> **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.

```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
```
> **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.

**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
yarn install
```

```sh
# With docker
docker run ghcr.io/hyperledger/afj-rest --help
2. **Build the project:**
```sh
yarn build
```

# Directly on computer
npx -p @aries-framework/rest afj-rest start --help
```
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 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.

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.
</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

First, you need to add these required parameters to `samples/cliConfig.json`:

```json
{
"label": "AFJ Rest Agent",
"walletId": "walletId",
"walletKey": "walletKey"
// ... other config options ... //
// ...existing configuration...
"walletConnectTimeout": 30,
"walletMaxConnections": 90,
"walletIdleTimeout": 30
// ...rest of configuration...
}
```

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 parameters are required to avoid wallet connection errors when using PostgreSQL.

```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 credo-postgres -d \
-e POSTGRES_DB=postgres \
-e POSTGRES_USER=postgres \
-e POSTGRES_PASSWORD=postgres \
-p 5432:5432 \
postgres:13
```

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
```

This method uses the official prebuilt image and connects to your local PostgreSQL instance.

> **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

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
```

</details>

## 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
)
Expand All @@ -140,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.

Expand All @@ -155,7 +225,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
Expand Down