Skip to content

Commit

Permalink
update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@jchartrand
jchartrand committed Mar 8, 2024
1 parent a6e0249 commit 7d0f36c
Show file tree
Hide file tree
Showing 2 changed files with 54 additions and 118 deletions.
135 changes: 17 additions & 118 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,142 +1,41 @@
# VC Admin Dashboard
# Admin Dashboard

THIS IS A FORK OF [https://github.com/learningeconomy/admin-dashboard](https://github.com/learningeconomy/admin-dashboard) AND IS A WORK-IN-PROGRESS. NOT INTENDED FOR GENERAL USE (YET).
CHECK OUT OUR [GETTING STARTED DOC](docs/GETTING_STARTED.md) FOR A STEP BY STEP GUIDE TO EVALUATING AND INSTALLING THIS SOFTWARE.

WE ARE WORKING TOWARDS A CONFIGURATION OF THIS SYSTEM THAT CAN BE INSTALLED EASILY, STARING WITH A BASIC EVALUATION VERSION THAT CAN BE STARTED UP WITH A SINGLE DOCKER COMMAND, AND THEN PROGRESSIVELY ADDING FEATURES LIKE STATUS MANAGEMENT AND MAIL-OUTS.

CHECK OUT OUR (IN-PROGESS) [GETTING STARTED DOC](docs/GETTING_STARTED.md) FOR A STEP BY STEP GUIDE TO EVALUATING AND INSTALLING THIS SOFTWARE.

[![Release Branch](https://img.shields.io/badge/release_branch-main-green.svg)](https://github.com/learningeconomy/admin-dashboard/tree/main)
[![Read the Docs](https://img.shields.io/badge/docs-quickstart-green.svg)](https://docs.learncard.com/)
[![License](https://img.shields.io/badge/license-mit-blue.svg)](https://github.com/learningeconomy/admin-dashboard/blob/main/LICENSE)
[![Release Branch](https://img.shields.io/badge/release_branch-main-green.svg)](https://github.com/digitalcredentials/admin-dashboard/tree/main)
[![License](https://img.shields.io/badge/license-mit-blue.svg)](https://github.com/digitalcredentials/admin-dashboard/blob/main/LICENSE)

<p float="left">
<img src="https://github.com/learningeconomy/admin-dashboard/assets/2185016/9926ded7-40e9-4f18-a89a-bd788274903e" width="200" />
<img src="https://github.com/learningeconomy/admin-dashboard/assets/2185016/31882ce0-ce6e-4661-8c42-e64958accfc3" width="350" height="0" />
<img src="https://github.com/learningeconomy/admin-dashboard/assets/2185016/31882ce0-ce6e-4661-8c42-e64958accfc3" width="350" />
</p>

A system for:

This open-source **VC Admin Dashboard** is a joint effort between the [Digital Credentials Consortium at MIT](https://digitalcredentials.mit.edu/) and the [Learning Economy Foundation](https://www.learningeconomy.io). It's designed to provide enterprises, schools, and organizations with a straightforward way to issue Verifiable Credentials in bulk.
* uploading and managing credential data
* issuing [Verifiable Credentials](https://www.w3.org/TR/vc-data-model/) from that data
* notifying recipients by email of credential entitlement
* enabling recipients to collect their credentials

## Features:

- **User Management**: Efficient user onboarding and management.
- **Credential Management**: Handle individual credentials—search, view, check status, and revoke.
- **User Management**: Create and manage user accounts.
- **Credential Management**: Manage individual credentials: searching, viewing, status checking, and revocation.
- **Batch Management**: Manage groups of credentials, such as annual diploma issuances.
- **VC & Email Template Management**: Edit and store templates for credentials and emails.
- **Claim Page**: Allows students to claim and download their credentials.
- **White Label Ready**: Configurable branding options.
- **VC-API & CHAPI Integration**: Compatible with the Verifiable Credential API exchange endpoints and CHAPI.
- **Claim Page**: Web page from which to claim and download credentials to a wallet.
- **VC-API**: Compatible with the Verifiable Credential API exchange endpoints.
- **Deployment**: Fully dockerized for ease of deployment.

NOTE: The claim page is packaged separately. Ultimately you can use any claim page you like, but here's one that works with the dashboard: [admin-dashboard-claim-page](https://github.com/digitalcredentials/admin-dashboard-claim-page).

## Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

[![Stargazers repo roster for @learningeconomy/admin-dashboard](https://reporoster.com/stars/learningeconomy/admin-dashboard)](https://github.com/learningeconomy/admin-dashboard/stargazers)

## Comments, Questions, or Palpitations of the Heart?
The best way to start engaging in the community is to participate in our Github Discussions:
- [Post an Issue or Ask for Help 💖](https://github.com/learningeconomy/admin-dashboard/issues)

## About the Repo

This repository houses the main services for the Admin Dashboard which include Claim Page, Dashboard, and DCC (Digital Credential Consortium) Services. The services are organized within separate directories and are dockerized for easy setup and deployment.

## Directory Structure

```plaintext
.
├── packages
│ └── claim-page
├── services
│ ├── payload
│ └── dcc-services
└── compose.yaml
```

## Services

### Claim Page

Located inside `packages/claim-page`, this service handles the webpage that users see when claiming
a credential.

- **Environment Setup**:
- A sample environment file is provided as `.env.sample`.
- Copy `.env.sample` to `.env` and replace the PUBLIC_PAYLOAD_URL with the URL to your Dashboard API.
- If running locally, the sample value of `http://localhost:3000/api` will be correct. Otherwise, this will be the URL of your Dashboard API!

### Dashboard
You'd typically configure it to run alongside the admin-dashboard in a docker compose as described in our [deployment guide](https://github.com/digitalcredentials/docs/blob/jc-compose-files/deployment-guide/DCCDeploymentGuide.md)

Located inside `services/payload`, this service provides the dashboard functionality for the application.

- **Environment Setup**:
- A sample environment file is provided as `.env.sample`.
- Copy `.env.sample` to `.env` and replace the dummy values with actual values for your setup.
- `MONGODB_URI`: URI for connecting to MongoDB. [See here for more information](https://www.mongodb.com/docs/manual/installation/)
- `PAYLOAD_SECRET`: A secret value to use when signing JWTs for authentication into the dashboard. You may use anything here, but please change it from the default and keep it safe!
- `COORDINATOR_URL`: If running locally, the sample value of `http://localhost:4005` will be correct. Otherwise, this will be the URL of the DCC Workflow Coordinator Service!
- `TENANT_NAME`: The tenant name used to sign credentials. This will need to match what you set up in the DCC Services!
- `STATUS_URL`: If running locally, the sample value of `http://localhost:4008` will be correct. Otherwise, this will be the URL of the DCC Credential Status Service!
- `SMTP_HOST`: The SMTP host to use for sending emails
- `SMTP_USER`: The SMTP user to use for sending emails
- `SMTP_PASS`: The SMTP password to use for sending emails
- `EMAIL_FROM`: The Email From to use by default when sending emails
- `CLAIM_PAGE_URL`: If running locally, the sample value of `http://localhost:8080` will be correct. Otherwise, this will be the URL of your Claim Page!
- `PAYLOAD_PUBLIC_SERVER_URL`: If running locally, the sample value of `http://localhost:3000` will be correct. Otherwise, this will be the URL of your Dashboard API!

### DCC Services

Located inside `services/dcc-services`, this service handles digital credential consortium functionalities. This includes three sub-services each with its own environment configuration:

- Coordinator Service
- Signing Service
- Status Service

- **Environment Setup**:
- Sample environment files are provided for each service as `.coordinator.env.sample`, `.signing-service.env.sample`, and `.status-service.env.sample`.
- More information on each configuration can be found [here](https://github.com/digitalcredentials/workflow-coordinator#configuration).
- Copy these sample files to `.coordinator.env`, `.signing-service.env`, and `.status-service.env` respectively, replacing the dummy values with actual values for your setup.
- `.coordinator.env`
- `ENABLE_STATUS_SERVICE`: Set this to true
- `PUBLIC_EXCHANGE_HOST`: This must be set to the API route of the Dashboard service.
- If running locally, you may use `http://localhost:3000/api`
- If running locally and you would like to test out the QR codes with your phone, you can use the command `ip a` to find your local IP, and set it to that (e.g. `http://192.168.68.68:3000/api`)
- At deploy time, this should be set to the API route of the live Dashboard service.
- `TENANT_TOKEN_${TENANT_NAME}`: This should be set to `UNPROTECTED` for now. We are not using JWTs for tenants (yet)
- `.signing-service.env`
- `TENANT_SEED_${TENANT_NAME}`: This should be set to a random, secure hex string to be used as the seed for signing VCs
- `.status-service.env`
- [See here for information about setting this up](https://github.com/digitalcredentials/status-service)
- Additionally, you'll want to set `CRED_STATUS_DID_SEED` to a secure random hex string to use as the seed for signing the Status Service VCs. This can, but does not have to, be different than the seed used in the signing service

## Deployment

The services are dockerized and a top-level `compose.yaml` is provided to orchestrate the deployment of the Claim Page, Dashboard, and all DCC services.

### Local Deployment

For local deployment, you can use Docker Compose to bring up the services:

```bash
docker-compose -f compose.yaml up
```

### Cloud Deployment

For cloud deployment (e.g., on an AWS EC2 instance), you can also use the provided `compose.yaml` file with Docker Compose. Alternatively, the containers for Claim Page and Dashboard are available on Docker Hub and can be run independently.

```bash
docker-compose -f compose.yaml up -d
```

---
## Contributing

**Note:** Ensure that you have Docker and Docker Compose installed on your machine for deploying the services.
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

## License
MIT © [MIT](#)
37 changes: 37 additions & 0 deletions docs/GETTING_STARTED.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@ It'll likely take a minute or two to download all the images from Docker Hub, bu

You've now got a working admin-dashboard up and running.

You'll initially be prompted to create a first user. Do that and then...

### Longer story

This guide now continues on, explaining the system and progressively helping you add features as you go.
Expand Down Expand Up @@ -175,3 +177,38 @@ So hopefully to this point you've gotten a sense of how things work on the admin
If you'd now like to get a sense of what the student sees, and how they collect their credentials, we've got to configure our application by specifying a mail server to send emails, and we need to expose our collection endpoint so the [Learner Credential Wallet](http://lcw.app) can collect our credentials.
Let's start with email...
#### Configure mail
You'll need an outgoing SMTP mail server like sendgrid or potentially your own current email address if you can directly send emails to your server.
Take a look at the [.env.sample](.env.sample) to see how to set the three variables for mail:
```
SMTP_HOST=<SMTP HOST>
SMTP_USER=<SMTP USER>
SMTP_PASS=<SMTP PASSWORD>
```
Once that's set you can now 'Send' your credentials as described in the prior step, but first...
#### Collection endpoint
You can now send out the emails, which will contain a link that the student can click
to collect their credentials. That link takes the student to a claim page from which they
can click another link that will open a wallet that will download the credential.
So we need to configure those two links for the claim page and collection endpoint. They are
similarly set in the the [.env.sample](.env.sample) as:
```
CLAIM_PAGE_URL=http://localhost:8080
PAYLOAD_PUBLIC_SERVER_URL=http://localhost:3000
```
The first is where the claim page runs, and the second is where the admin-dashboard (this repo) runs.
The defaults are set to localhost, but to be useful with the wallet, which is an app that runs on a phone, they'll have to be set to a publically accessible url. This is the point where you
need to deploy your app to a server with a public IP or domain name. Essentially, you'll need to run the same docker compose, but on a public server, ideally with a domain name, then set it for the claim page and dashboard.
We've got another docker compose file that you can use as a template that includes nginx configurations to support your domain name and certificates. TODO add nginx compose.

0 comments on commit 7d0f36c

Please sign in to comment.