Skip to content

Commit 7add53b

Browse files
committed
Add quickstart guide for ohttp-relay on basic ubuntu server
This issue payjoin/ohttp-relay#37 outlines a need for some documentation for a quickstart guide on a docker server with a nginx proxy. This iteration uses the existing dockerfile with a nginx reverse proxy in front.
1 parent 9ea05ed commit 7add53b

File tree

1 file changed

+118
-0
lines changed

1 file changed

+118
-0
lines changed
+118
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# Quickstart ohttp relay
2+
3+
We'll demonstrate how you can setup an ohttp server on common cloud insfrastructure on something like [AWS Ubuntu](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/gs-ubuntu.html) using the `ohttp-relay` crate in Payjoin Dev Kit. This should take about 30 minutes.
4+
5+
## Initial server setup
6+
7+
We will be using a basic Ubuntu server in our tutorial. In this tutorial we will be running the server as a docker container with nginx as a TLS proxy.
8+
9+
First, you must install docker and nginx on your server.
10+
11+
Install docker, nginx and the ningx stream module on a fresh Ubuntu server:
12+
13+
```sh
14+
sudo apt update && sudo apt upgrade -y # Ubuntu
15+
16+
sudo apt install -y docker.io nginx libnginx-mod-stream #libnginx-mod-stream gives us access to the nginx stream module
17+
18+
sudo systemctl start docker nginx
19+
sudo systemctl enable docker nginx
20+
```
21+
22+
## Deploy ohttp-relay with Docker
23+
24+
We will want to build our docker image for our server to run as a container from.
25+
26+
Clone our ohttp-relay from github and then build the docker image.
27+
28+
```sh
29+
git clone https://github.com/payjoin/ohttp-relay.git
30+
31+
cd ohttp-relay
32+
33+
sudo docker build -t ohttp-relay .
34+
```
35+
36+
## Configure Nginx as a Reverse Proxy
37+
38+
Edit the existing `nginx.conf`.
39+
40+
```sh
41+
#/etc/nginx/nginx.conf
42+
load_modules /usr/lib/nginx/modules/ngx_mod_stream.so;
43+
error_log /var/log/nginx/error.log debug;
44+
pid /var/run/nginx.pid;
45+
46+
events {
47+
worker_connections 1024;
48+
}
49+
50+
stream {
51+
server {
52+
listen 80;
53+
54+
proxy_pass 127.0.0.1:3000;
55+
}
56+
57+
server {
58+
listen 443 ssl;
59+
60+
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
61+
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
62+
63+
proxy_pass 127.0.0.1:3000;
64+
}
65+
}
66+
```
67+
68+
## Get a certificate
69+
70+
We need a valid TLS certificate from a Certificate Authority. The simplest option is to use [certbot](https://certbot.eff.org/instructions).
71+
Once certbot is installed, we can obtain a certificate but because we are using the stream module we will need to ensure that the certificate path is correct as certbot cannot correct this automatically in this case.
72+
73+
```sh
74+
sudo certbot certonly --standalone -d example.com
75+
```
76+
77+
Confirm that the path to your ssl_cert and key are correct in your nginx.conf.
78+
79+
```sh
80+
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
81+
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
82+
```
83+
84+
Restart your nginx service
85+
86+
```sh
87+
sudo systemctl restart nginx
88+
```
89+
90+
## Ensure the ohttp-relay runs persistently
91+
92+
We can use some built-in flags in docker to run our ohttp-relay in the background.
93+
94+
```sh
95+
sudo docker run -d --restart unless-stopped --name ohttp-relay -p 3000:3000 \
96+
-e PORT=3000 \
97+
-e GATEWAY_ORIGIN=https://payjo.in \
98+
ohttp-relay
99+
```
100+
101+
the `-d` flag ensures that our container will be running in the background and `--restart unless stopped` will ensure persistence even after logging and server reboots.
102+
103+
That's all it takes to setup an ohttp-relay. The looping allows a sender to send a proposal and receive a Payjoin in an asynchronous way. When you run this program you will participate in coordinating payjoins by relaying data between senders and receivers without leaking their IPs to each other or the payjoin directory.
104+
105+
## Testing
106+
107+
Check your work by running the curl request below to do a quick check to make sure your server is receiving well.
108+
109+
For testing we will include th `-vk and --proxy-insecure` flags to ensure we can get past any warnings or errors our curl request might send us with invalid cert signatures. For final checks in prod we recommend removing these flags to ensure your keys and certs are working and up-to-date.
110+
111+
This curl request should occur in 2 stages
112+
1. The proxy CONNECT request that passes through your relay to the `https://payjo.in` directory
113+
2. The GET request on `/ohttp-keys` that will return a binary encoded output
114+
A successful test should return a 200/OK response on both of these steps
115+
116+
```sh
117+
curl -vk --proxy-insecure --proxy https://{your-relay-public-ip} https://payjo.in/ohttp-keys --output - | xxd -p
118+
```

0 commit comments

Comments
 (0)