acapy-cloud

🚧 This project is currently under development. If you would like to use this in production, please contact us first to discuss your use case.

✅ You should be able to deploy this project in a local environment using the Quick Start Guide

Overview

This project comprises a FastAPI application built around ACA-Py, primarily tailored for Yoma-specific use cases.

The main app provides an API interface that simplifies complex self-sovereign identity (SSI) workflows. Using our ACA-Py controller, it provides a streamlined layer of abstraction for client applications (e.g., a mobile app) to interact within an SSI ecosystem.

What would normally require multiple calls to ACA-Py can be condensed into a single call through this API. For example, onboarding an issuer — which involves creating a wallet, establishing a connection with an endorser, generating a public DID, accepting the Transaction Author Agreement (TAA), publishing the DID to the ledger, and awaiting confirmation — can all be achieved with a single API call. Convenient, isn't it?

We simplify several key capabilities, including:

• Creating and managing wallets
• Onboarding issuers and verifiers
• Managing connections between parties
• Creating schemas and credential definitions
• Issuing verifiable credentials and handling revocations
• Requesting and validating proofs

To enable this, the project includes essential supporting services:

• An Endorser agent and service for authorizing ledger transactions
• A Trust Registry implementation for authorizing valid issuers, verifiers, and approved credential schemas
• A webhooks service (Waypoint) for real-time, server-sent event (SSE) notifications and updates

For detailed documentation, please refer to the docs folder. We recommend:

• Quick Start Guide - Get up and running quickly
• Main Documentation - Detail on the different services, roles, authentication, and further reading
• Common Steps - Quick steps for creating tenants, issuing credentials, and requesting proofs
• Example Flows - More involved, step-by-step examples

How to Run It

Note

For local development we now use Tilt and Kind instead of Docker Compose. Legacy Docker Compose files are still available, but deprecated and will be removed in the future.

Running the project is straightforward — it's all containerized. Simply execute mise run tilt:up from the project root. This command will spin up a Kind cluster, build all the necessary docker images, and start the project. You can then visit localhost:10350 to access the Tilt UI.

For detailed setup instructions and requirements, see the Quick Start Guide.

Running Tests

The tests use pytest. For convenience, use Mise to run them. First, ensure the project is running locally by executing mise run tilt:up. In another shell, you can now run mise run tests to run all tests or mise run tests:unit to run only the unit tests.

mise run tilt:up

Install the requirements:

mise run poetry:install

To run the tests you need to set up some environment variables to point Pytest at the correct endpoints.

cp .env.example .env
source .env

Then you can run the tests:

poetry run pytest .

Or only the unit tests:

poetry run pytest --ignore=app/tests/e2e

You can specify the log level of the pytest output by using the --log-cli-level flag.

poetry run pytest . --log-cli-level=DEBUG

This will output all log messages with a log level of DEBUG or higher.

To run specific tests, you can specify the path to the test file and the test method. For example:

poetry run pytest \
  app/tests/e2e/test_verifier_oob.py::test_accept_proof_request_oob \
  --log-cli-level=1

Running containerised tests

mise run tilt:up

In another terminal:

# Run e2e tests
helm upgrade --install acapy-test \
  -f ./helm/acapy-test/conf/local/values.yaml \
  ./helm/acapy-test

# Bootstrap regression tests
helm upgrade --install acapy-regression-test \
  -f ./helm/acapy-test/conf/local/values.yaml \
  -f ./helm/acapy-test/conf/local/regression.yaml \
  --set env.FAIL_ON_RECREATING_FIXTURES=false \
  ./helm/acapy-test

# Run regression tests
helm upgrade --install acapy-regression-test \
  -f ./helm/acapy-test/conf/local/values.yaml \
  -f ./helm/acapy-test/conf/local/regression.yaml \
  --set env.FAIL_ON_RECREATING_FIXTURES=true \
  ./helm/acapy-test

Note

At the time of writing, if you are running tests on an ARM based machine, it is expected that bbs tests will fail as bbs is not currently supported on ARM.

CI/CD

Please, refer to the CI/CD docs for more information.

Contributing

While this project was primarily developed to meet the needs of Yoma, it is an open-source project that can be used for other Hyperledger Aries projects as well. We welcome contributions from everyone. Feel free to engage in discussions, create pull requests against existing tickets, or open new issues following the GitHub guidelines.