Skip to content
This repository was archived by the owner on Mar 8, 2024. It is now read-only.

Commit 08a6fd6

Browse files
LoisRPLoisRP
authored
Reorg of docs - prepare to merge (#115)
* reorganized docs for 1st iteration * modified sidebar * re-add images as part of reorg * split up PayID CLI doc * removed PayID CLI tutorial because covered by Verifiable PayID tutorial * added tutorial for Xpring and PayID based on demo * updates as suggested by reviewers
1 parent b1a0335 commit 08a6fd6

17 files changed

Lines changed: 395 additions & 203 deletions

‎docs/best-practices.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
id: payid-best-practices
3-
title: Security
4-
sidebar_label: Security
3+
title: Security Best Practices
4+
sidebar_label: Security Best Practices
55
---
66

77
The PayID protocol is flexible and supports a wide range of implementations. To ensure security, follow these best practices.

‎docs/getting-started.md‎

Lines changed: 28 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ title: Getting Started
44
sidebar_label: Getting Started
55
---
66

7-
PayID is a simple, web-based protocol designed to make it as easy to send someone money as it is to send them an email. This guide walks you through:
7+
PayID is a simple, web-based protocol designed to make it as easy to send someone money as it is to send them an email. This guide walks you through the following.
88

99
- [Experiment With the PayID Sandbox](#experiment-with-the-payid-sandbox)
1010
- [Run a PayID Server](#run-a-payid-server)
@@ -21,13 +21,24 @@ The [PayID Sandbox](https://payid.org/sandbox) lets you experiment with PayID in
2121

2222
To use [PayID Sandbox](https://payid.org/sandbox), log in with your Github account and follow the prompts. You can quickly set up a virtual test server, and then create users with simple PayID addresses that map to addresses on various networks such as XRPL, Interledger, BTC, and ETH. Using the provided cURL or Javascript code, you can create, update, and delete users, and get payment information about a PayID address. While the session is running, you can also run operations from your command line.
2323

24-
## Set up your own PayID server
24+
## Run a PayID Server
2525

26-
You have several options to set up your own PayID server. See [Deployment Options](intro-deploy). For preliminary development and testing, try deploying locally, with or without Docker.
26+
To familiarize yourself and experiment with PayID, you can set up a local PayID server. Here is a simple method. For more options, including PayID deployment for production environments, see [Deployment Overview](intro-deploy).
27+
28+
1. If you haven't already, install [Docker](https://docks.docker.com/get-docker/) and [Node](https://nodejs.org/en/) on your machine.
29+
30+
2. The reference implementation server is available at [https://github.com/payid-org/payid](https://github.com/payid-org/payid). You can download the reference implementation server by cloning the repository at the command line:
31+
`git clone https://github.com/payid-org/payid.git`
32+
33+
3. Go to the `/payid` directory that you just created:
34+
`cd payid`
35+
36+
4. Boot up the PayID HTTP server and a Postgres database to develop against:
37+
`npm run devEnvUp`
2738

2839
## Create a PayID
2940

30-
Now that you have a PayID server running, you can create a PayID. If your server was publicly accessible, other people could query your account information from your PayID server.
41+
Now that you have a PayID server running, you can create a PayID. If your server is publicly accessible, other people could query your account information from your PayID server.
3142

3243
To create a PayID, with an [XRP Ledger Testnet account](https://xrpl.org/xrp-testnet-faucet.html), send this request to your server:
3344

@@ -115,9 +126,21 @@ If you want to clean up the Docker containers, you can run `npm run devDown`.
115126

116127
Now that you've set up the basics, [learn more](#learn-more) about PayID and what you can do with it.
117128

129+
## Xpring SDK Integration
130+
131+
PayID support is integrated into [Xpring SDK](https://github.com/xpring-eng/xpring-sdk).
132+
133+
Xpring SDK provides the ability to work with PayID. It provides three language libraries:
134+
135+
- [JavaScript](https://github.com/xpring-eng/xpring-js)
136+
- [Java](https://github.com/xpring-eng/xpring4j)
137+
- [Swift](https://github.com/xpring-eng/xpringkit)
138+
139+
These libraries help you connect your application to PayID without having to worry about the specifics of PayID. Try [Get Started With Xpring SDK and PayID](xpring-sdk-payid-get-started).
140+
118141
## Learn More
119142

120-
After setting up the basics, you have a good foundation for learning more about the PayID Protocol. Here are some next steps you can take:
143+
You now have a good foundation for learning more about the PayID Protocol. Here are some next steps you can take:
121144

122145
- [How to convert](https://github.com/xpring-eng/xpring-js#usage-payid) the `user$domain.com` format to a URL
123146
- Learn how to use relevant [HTTP headers](payid-headers)
@@ -133,11 +156,3 @@ Learn about:
133156
- [How to contribute to PayID](https://github.com/payid-org/payid/blob/master/CONTRIBUTING.md)
134157
- [PayID RFCs](https://github.com/payid-org/rfcs), which discuss potential changes and additions to the PayID Protocol
135158
- The [PayID Whitepaper](https://payid.org/whitepaper.pdf), which provides background context around the problems that PayID solves
136-
137-
## Xpring SDK Integration
138-
139-
PayID is integrated into [Xpring SDK](https://github.com/xpring-eng/xpring-sdk).
140-
141-
Xpring SDK provides the ability to work with PayID, using libraries provided in [JavaScript](https://github.com/xpring-eng/xpring-js), [Java](https://github.com/xpring-eng/xpring4j), and [Swift](https://github.com/xpring-eng/xpringkit).
142-
143-
These libraries help you connect your application to PayID without having to worry about the specifics of PayID.

‎docs/intro-deploy.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,3 +15,5 @@ When you want to experiment with or deploy a PayID server, you have several opti
1515
- [Deploy on AWS Lambda](aws-lambda-deploy)
1616

1717
You can use the same principles to deploy a PayID server on other cloud providers, or on your own machines. See the suggested [requirements](payid-server-requirements).
18+
19+
When you have set up your PayID server, you can also configure an [NGINX reverse proxy and SSL](nginx-ssl-deploy) to improve load bearing and security.

‎docs/local-deployment.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ sidebar_label: Deploy Locally Without Docker
66

77
## Basic requirements
88

9-
Ensure your system meets these requirements before you set up a PayID server.
9+
Make sure your system meets these requirements before you set up a PayID server.
1010

1111
- RAM: Minimum of 100 MB
1212
- Postgres: 11.7 or later, with [pgpool-II](https://www.pgpool.net) in front

‎docs/metrics-tutorial.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
---
2+
id: metrics-tutorial
3+
title: Metrics Tutorial
4+
sidebar_label: Metrics Tutorial
5+
---
6+
7+
## Deploy a PayID server with Docker, and pull PayID metrics into Prometheus
8+
9+
In this tutorial, you will deploy a PayID server and run Prometheus locally using Docker, and you will create a configuration file for the PayID server so that PayID metrics are pulled into Prometheus.
10+
11+
### Prerequisites
12+
13+
Install the following software on your machine, if not already present.
14+
15+
- [npm](https://www.npmjs.com/get-npm)
16+
- [docker](https://docs.docker.com/get-docker/)
17+
- [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
18+
19+
### Build a Docker container for setting up a PayID server
20+
21+
Run these commands to build a Docker container for a PayID server.
22+
23+
```bash
24+
git clone https://github.com/payid-org/payid.git
25+
cd payid
26+
docker build -t payid-server .
27+
```
28+
29+
### Create Docker network for PayID
30+
31+
You will run several containers in Docker that must talk to each other. To set up these containers, create a docker network called `payid-network`.
32+
33+
```bash
34+
docker network create payid-network
35+
```
36+
37+
### Start a Postgres Database
38+
39+
To have a PayID server, you require a Postgres database to store PayID accounts and address mappings. To do this, run the postgres database in docker with a default password of `password`, and tell the database to use the `payid-network` that you previously created. Name this docker container `payid-postgres`, so that you can reference the container by name when you connect your PayID server. Note that both the default database and the user are named `postgres`, as described at [Postgres Docker Official Images](https://hub.docker.com/_/postgres).
40+
41+
```bash
42+
docker run -d --rm --name payid-postgres --network payid-network -e POSTGRES_PASSWORD=password postgres
43+
```
44+
45+
### Start and test the PayID server
46+
47+
To start the PayID server, run the PayID server in docker using the image you created. You must also use the docker network `payid-network` so that it can connect to the `payid-postgres` container.
48+
49+
```bash
50+
docker run -it -p 8080:8080 -p 8081:8081 --name payid-server --network payid-network -e DB_PASSWORD=password -e
51+
DB_NAME=postgres -e DB_HOSTNAME=payid-postgres payid-server
52+
```
53+
54+
Test whether the PayID server is running by creating a PayID with this cURL command.
55+
56+
```bash
57+
curl --location --request POST 'http://127.0.0.1:8081/users' --header 'PayID-API-Version: 2020-06-16' --header 'Content-Type: application/json' --data-raw '{
58+
"payId": "charlie$127.0.0.1",
59+
"addresses": [
60+
{
61+
"paymentNetwork": "XRPL",
62+
"environment": "TESTNET",
63+
"details": {
64+
"address": "rDk7FQvkQxQQNGTtfM2Fr66s7Nm3k87vdS"
65+
}
66+
}
67+
]
68+
}'
69+
```
70+
71+
You should get a `Created` response.
72+
73+
Query the PayID server to make sure it resolves, using this cURL command.
74+
75+
```bash
76+
curl http://127.0.0.1:8080/charlie -H "PayID-Version: 1.0" -H "Accept: application/xrpl-testnet+json"`
77+
```
78+
79+
### Start Prometheus
80+
81+
In this step, you will run prometheus in docker and configure it to scrape the PayID server’s metrics. To do this, you need to create a `prometheus.yml` file on the host machine and mount it in the docker container.
82+
83+
Create a file named `prometheus.yml` with these contents.
84+
85+
```yml
86+
global:
87+
scrape_interval: 15s # Set the scrape interval to every 15 seconds. Default is every 1 minute.
88+
evaluation_interval: 15s # Evaluate rules every 15 seconds. The default is every 1 minute.
89+
90+
scrape_configs:
91+
- job_name: 'payid-metric'
92+
honor_labels: true
93+
static_configs:
94+
- targets: ['payid-server:8081']
95+
```
96+
97+
Start the docker container:
98+
99+
```bash
100+
docker run -d --network payid-network -p 9090:9090 -v $PWD/prometheus.yml:/etc/prometheus/prometheus.yml prom/prometheus`
101+
```
102+
103+
You can verify Prometheus is running by opening `http://localhost:9090/graph` in a browser.
104+
105+
You can verify metrics collection metrics are being collected by entering the following expression into the form:
106+
107+
`sum(payid_count)`
108+
109+
Click `Execute`. If successful, the results look like this:
110+
111+
![PayID Metrics setup and configuration](/img/docs/prometheus-sum.png)
112+
113+
Click the **Graph** tab to display the results in graph format.
114+
115+
Here are some other example expressions:
116+
117+
- `sum(payid_count) by (paymentNetwork)` - Sum of `payid` count by payment network, such as XRPL, BTC, and so forth.
118+
- `sum(payid_lookup_request)` - Total number of `payid` lookup requests.
119+
- `rate(payid_lookup_request[5m])` - Rate of `payid` lookup requests per second.

‎docs/nginx-ssl-deploy.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
id: nginx-ssl-deploy
3+
title: Set Up NGINX Reverse Proxy and SSL
4+
sidebar_label: Set Up NGINX Reverse Proxy and SSL
5+
---
6+
7+
After you set up a PayID server using your preferred [deployment option](intro-deploy.md), you can set up NGINX Reverse Proxy + SSL for load balancing and security.
8+
9+
## NGINX Reverse Proxy + SSL setup
10+
11+
1. Change the PayID server to run on port 8080 (default).
12+
2. Set up a Server Block on NGINX for your domain, following [these instructions](https://www.digitalocean.com/community/tutorials/how-to-install-nginx-on-ubuntu-18-04).
13+
3. Install Certbot, as follows.
14+
```bash
15+
apt-get update
16+
apt-get install software-properties-common
17+
add-apt-repository ppa:certbot/certbot
18+
apt-get update
19+
apt-get install python-certbot-nginx
20+
```
21+
4. Generate a certificate (choose to redirect)
22+
`certbot --nginx`
23+
5. Change the location parameter in the NGINX conf file to reverse proxy to the PayID server (running on port 8080):
24+
`try_files $uri $uri/ =404;`
25+
to:
26+
```nginx
27+
proxy_pass http://127.0.0.1:8080;
28+
proxy_set_header Host $http_host;
29+
```
30+
**Note:** The second line is required to preserve the original URL, which is used to find the user.
31+
**Note:** You can expand your certificate to cover any subdomain used in a PayID using:
32+
`sudo certbot -d zochow.ski,pay.michael.zochow.ski,www.zochow.ski --expand`
33+
6. Restart NGINX.
34+
`sudo systemctl restart nginx`
35+
7. [Optional] Update the NGINX configuration that catches PayID headers and forwards them to the PayID server; otherwise, send these headers to the web server.
36+
37+
**Note:** You will need to add additional proxy passing statements for each additional network supported, or otherwise use a generic regex to identify all PayID headers.
38+
39+
```bash
40+
sudo nano /etc/nginx/sites-available/<your-site>
41+
```
42+
43+
```nginx
44+
location / {
45+
proxy_set_header Host $http_host;
46+
# needed for CORS
47+
add_header Access-Control-Allow-Origin *;
48+
add_header Access-Control-Allow-Headers *;
49+
50+
# proxy passing needed for all supported networks
51+
# modify port to the one used by your PayID server
52+
if ($http_accept ~ "application/payid*") {
53+
proxy_pass http://localhost:8080;
54+
}
55+
if ($http_accept ~ "application/xrpl-*") {
56+
proxy_pass http://localhost:8080;
57+
}
58+
59+
try_files $uri $uri/ =404;
60+
}
61+
```

‎docs/payid-cli-reference.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
id: payid-cli-reference
3+
title: PayID CLI Reference
4+
sidebar_label: PayID CLI Reference
5+
---
6+
7+
Use these commands with PayID CLI. See [PayID CLI](payid-cli) for setup information.
8+
9+
| Command | Description |
10+
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
11+
| `help [command...]` | Provides help for a given command. |
12+
| `exit` | Exits application. |
13+
| `clear` | Clears the terminal. |
14+
| `crypto-address add <paymentNetwork> <environment> <address> [tag]` | Starts building a new PayID. |
15+
| `crypto-address remove <address>` | Removes an address from the current PayID. |
16+
| `keys clear` | Clears all loaded keys. |
17+
| `keys generate` | Generates and saves a new identity key. |
18+
| `keys list` | Lists keys that have been loaded. |
19+
| `keys load <filePath>` | Loads identity-key from file. |
20+
| `keys print` | Prints keys that have been loaded in pem format. |
21+
| `init <payid>` | Initializes a new PayID. |
22+
| `inspect [payId]` | Inspects signatures on the loaded PayID or from an optionally specified PayID. |
23+
| `load <payId>` | Loads a PayID from PayID server. |
24+
| `show` | Shows the currently loaded PayID. |
25+
| `sign` | Signs the loaded PayID with the loaded signing keys. |
26+
| `verify [payId]` | Verifies the loaded PayID or an optionally specified PayID. |
27+
| `save` | Saves the currently loaded PayID. |
28+
| `from-url <url>` | Converts a URL to a PayID. |
29+
| `to-url <payId>` | Converts a PayID to a URL. |

0 commit comments

Comments
 (0)