Skip to content

README.md

Latest commit

 

History

History
170 lines (122 loc) · 4.3 KB

README.md

File metadata and controls

170 lines (122 loc) · 4.3 KB

UniformID Registrar

A web-based DID (Decentralized Identifier) service built with Veramo and Express.js. This service provides a REST API for managing Web DIDs and their associated services.

Important Note: This open-source version has authentication removed to keep it simple. Users must apply their own business logic and security measures. Reach out to 1EdTech if you need assistance with enterprise-grade authentication and security.

Features

  • Create and manage Web DIDs
  • Add and remove DID services
  • Manage DID aliases (AlsoKnownAs)
  • DID document resolution
  • Support for multiple database backends (SQLite, MySQL, PostgreSQL)
  • Docker and Kubernetes support

Prerequisites

  • Node.js 20 or later
  • npm or yarn
  • Docker (optional)
  • Kubernetes (optional)

Quick Start

Option 1: Using Docker Compose (Recommended)

The easiest way to get started is using Docker Compose with MariaDB:

  1. Start the development environment (with hot-reloading):
docker-compose up registrar-dev
  1. Or start the production build:
docker-compose up registrar

Both services run on port 3000. The development version is recommended for local development as it provides hot-reloading and detailed logging.

Option 2: Local Development

  1. Install dependencies:
npm install
  1. Configure environment variables:
cp .env.example .env

Edit the .env file with your configuration.

  1. Start the development server:
npm run dev
  1. Build and start production:
npm run build
npm start

Option 3: Using Docker

You can run the registrar using Docker with the following command:

docker run -p 3000:3000 \
  --name uniformid-registrar \
  -e PORT=3000 \
  -v ~/.uniformid-data:/data \
  uniformid-registrar:local

Configuration

The service can be configured using environment variables:

Database Configuration

# Database Type (sqlite, mysql, or postgres)
DB_TYPE=sqlite

# Database Synchronization
DB_SYNCHRONIZE=true

# Database Logging
DB_LOGGING=false

# SQLite Configuration
DB_DATABASE=veramo.sqlite

# MySQL Configuration
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=your_password
DB_DATABASE=veramo

# PostgreSQL Configuration
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=your_password
DB_DATABASE=veramo

Server Configuration

# Port to run the server on
PORT=3000

# DID Web Configuration
DID_WEB_HTTP=true
DID_WEB_PORT=3000

API Endpoints

DID Resolution

  • GET /.well-known/did.json - Resolve the domain's DID document
  • GET /:id/did.json - Resolve a specific DID document

DID Management

  • POST /:encodedDid - Create a new DID
  • GET /:encodedDid - Get a DID document
  • DELETE /:encodedDid - Delete a DID

Service Management

  • POST /:encodedDid/services - Add a service to a DID
  • DELETE /:encodedDid/services/:serviceName - Remove a service from a DID

Alias Management

  • POST /:encodedDid/aliases - Add an alias to a DID
  • DELETE /:encodedDid/aliases/:alias - Remove an alias from a DID

Development with ngrok

Since Web DIDs require HTTPS/TLS, you can use ngrok for local development:

  1. Install ngrok: npm install -g ngrok or download from ngrok.com
  2. Start your registrar service on port 3000
  3. Create a tunnel: ngrok http 3000
  4. Use the provided HTTPS URL as your domain for DID creation

Example: did:web:abc123.ngrok.dev:user:bob resolves to https://abc123.ngrok.dev/user/bob.json

Testing

Import the Postman collection from the postman/ directory to test the APIs:

  • UniformIDOpenSource.postman_collection.json - Complete API test collection
  • LocalDev.postman_environment.json - Environment configuration for local development

Troubleshooting

Common Issues

  1. Port already in use: Change the PORT environment variable or stop other services using port 3000
  2. Database connection issues: Check your database configuration and ensure the database is running
  3. TLS/HTTPS requirements: Use ngrok or a proper domain with SSL for Web DID resolution

Logs

The service uses Winston for logging. Check the console output for detailed error messages and debugging information.

Support

For enterprise support, authentication integration, or custom implementations, please reach out to 1EdTech.