Merge pull request #23 from cloudflare/caw/add-metal-instructions

Add instructions for deploying on a bare metal.

README.md

@@ -4,11 +4,6 @@
 
 [Oblivious DoH Server](https://tools.ietf.org/html/draft-pauly-dprive-oblivious-doh)
 
-# Preconfigured Deployments
-
-[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy)
-[![deploy to Scalingo](https://cdn.scalingo.com/deploy/button.svg)](https://my.scalingo.com/deploy)
-
 # Local development
 
 To deploy the server locally, first acquire a TLS certificate using [mkcert](https://github.com/FiloSottile/mkcert) as follows:
@@ -24,6 +19,8 @@ $ make all
 $ CERT=cert.pem KEY=key.pem PORT=4567 ./odoh-server
 ~~~
 
+By default, the proxy listens on `/proxy` and the target listens on `/dns-query`.
+
 You may then run the [corresponding client](https://github.com/cloudflare/odoh-client-go) as follows:
 
 ~~~
@@ -39,7 +36,67 @@ cloudflare.com.	271	IN	AAAA	2606:4700::6810:84e5
 cloudflare.com.	271	IN	AAAA	2606:4700::6810:85e5
 ~~~
 
-# Usage
+# Deployment
+
+This section describes deployment instructions for odoh-server-go.
+
+## Preconfigured deployments
+
+[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy)
+[![deploy to Scalingo](https://cdn.scalingo.com/deploy/button.svg)](https://my.scalingo.com/deploy)
+
+## Manual deployment
+
+This server can also be manually deployed on any bare metal machine, or in cloud providers such
+as GCP. Instructions for both follow.
+
+### Bare metal
+
+Deployment on bare metal servers, such as [Equinix](https://metal.equinix.com/), can be done following
+the instructions below. These steps assume that `git` and `go` are both installed on the metal.
+
+1. Configure a certificate on the metal using [certbot](https://certbot.eff.org/all-instructions).
+Once complete, the output should be something like the following, assuming the server domain name
+is "example.com":
+
+```
+Successfully received certificate.
+Certificate is saved at: /etc/letsencrypt/live/example.com/fullchain.pem
+Key is saved at:         /etc/letsencrypt/live/example.com/privkey.pem
+```
+
+You must configure certbot to renew this certificate periodically. The simplest way to do this is
+via a cron job:
+
+```
+$ 00 00 1 * 1 certbot renew
+```
+
+2. Configure two environment variables to reference these files:
+
+```
+$ export CERT=/etc/letsencrypt/live/example.com/fullchain.pem
+$ export KEY=/etc/letsencrypt/live/example.com/privkey.pem
+```
+
+3. Clone and build the server:
+
+```
+$ git clone [email protected]:cloudflare/odoh-server-go.git
+$ cd odoh-server-go
+$ go build ./...
+```
+
+4. Run the server:
+
+```
+$ PORT=443 ./odoh-server &
+```
+
+This will run the server until completion. You must configure the server to restart should it
+terminate prematurely.
+
+### GCP
 
 To deploy, run:
 
@@ -62,16 +119,7 @@ To stream logs when deployed, run
 $ gcloud app logs tail -s default
 ~~~
 
-To run locally build and run the project using
-
-```shell
-go build
-PORT=8080 ./odoh-server-go
-```
-
-By default, the proxy listens on `/proxy` and the target listens on `/dns-query`.
-
-## Reverse proxy
+### Reverse proxy
 
 You need to deploy a reverse proxy with a valid TLS server certificate
 for clients to be able to authenticate the target or proxy.