rewrote readme

1 files changed, 208 insertions, 12 deletions

diff --git a/README.md b/README.md
index b859819..f3d6f53 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,22 @@
-# getwtxt [![Build Status](https://travis-ci.com/getwtxt/getwtxt.svg?branch=master)](https://travis-ci.com/getwtxt/getwtxt)
+# getwtxt [![Go Report Card](https://goreportcard.com/badge/github.com/getwtxt/getwtxt)](https://goreportcard.com/report/github.com/getwtxt/getwtxt) [![Build Status](https://travis-ci.com/getwtxt/getwtxt.svg?branch=master)](https://travis-ci.com/getwtxt/getwtxt)
 
 twtxt registry written in Go! 
 
+twtxt is a decentralized microblogging platform "for hackers" based
+on text files. The user is "followed" and "mentioned" by referencing the URL to
+their `twtxt.txt` (or other text) file and a (not necessarily unique) nickname.
+Registries are designed to aggregate several users' statuses into a single location,
+facilitating the discovery of new users to follow and allowing the search of statuses
+for tags and key words.
+
+Until now, there has primarily been a single registry application available for 
+enthusiasts to use to run their own `twtxt` registry. Why not add some diversity
+to the landscape?
+
+\[ [Installation](#installation) \] \[ [Configuration](#configuration) \] \[ [Using the Registry](#using-the-registry) \] \[ [Benchmarks](#benchmarks) \] \[ [Notes](#notes) \]
+
+## Features
+
 * Easy to set up and maintain. 
 * Uses an in-memory cache to serve requests.
 * Pushes to `LevelDB` at a configurable interval for data storage. 
@@ -10,20 +25,201 @@ twtxt registry written in Go!
 A public instance is currently available:
 * [twtxt.tilde.institute](https://twtxt.tilde.institute)
 
-## Development Progress
+## Installation 
+
+First, fetch the sources using either the `go` tool or using `git` (if you haven't 
+set up a `go` development environment and just want to try it out) and jump into
+the directory.
+
+```
+$ go get github.com/getwtxt/getwtxt
+...
+$ cd $GOPATH/src/github.com/getwtxt/getwtxt
+```
+
+```
+$ git clone git://github.com/getwtxt/getwtxt.git
+...
+$ cd getwtxt
+```
+
+Optionally, use the `go` tool to test and benchmark it:
+
+```
+$ go test -v -bench . -benchmem
+```
+
+Use the `go` tool to build:
+
+```
+$ go build -v
+```
+
+## Configuration
+
+\[ [Proxying](#proxying) \] \[ [Starting getwtxt](#starting-getwtxt) \]
+
+To configure `getwtxt`, you'll first need to open `getwtxt.yml` in your favorite
+editor and modify any values necessary. There are comments in the file explaining
+each option. Additionally, you may run `getwtxt` with the `-m` flag for a short
+configuration manual.
+
+```
+$ ./getwtxt -m | less
+```
+
+If you desire, you may additionally modify the template in `assets/tmpl/index.html`
+to customize the page users will see when they pull up your registry instance in
+a web browser. The values in the configuration file under `Instance:` are used
+to replace text `{{.Like This}}` in the template.
+
+### Proxying
+
+Though `getwtxt` will run perfectly fine facing the internet directly, it does not
+understand virtual hosts, nor does it use TLS (yet). You'll probably want to proxy it behind
+`Caddy` or `nginx` for this reason. 
+
+`Caddy` is ludicrously easy to set up, and automatically handles `TLS` certificates. Here's the config:
+
+```caddyfile
+twtxt.example.com 
+proxy / example.com:9001
+```
+
+If you're using `nginx`, here's a skeleton config to get you started:
+
+```nginx
+server {
+    server_name twtxt.example.com;
+    listen [::]:443 ssl http2;
+    listen 0.0.0.0:443 ssl http2;
+    ssl_certificate /etc/letsencrypt/live/twtxt.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/twtxt.example.com/privkey.pem;
+    include /etc/letsencrypt/options-ssl-nginx.conf;
+    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
+    location / {
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $remote_addr;
+        proxy_pass http://127.0.0.1:9010;
+    }
+}
+server {
+    if ($host = twtxt.example.com) {
+        return 301 https://$host$request_uri;
+    }
+    listen 80;
+    server_name twtxt.example.com;
+    return 404;
+}
+```
+
+### Starting `getwtxt`
+
+Once you've customized the configuration, start it within a `tmux` session (or `screen` works) and detach.
+If you're using a configuration file not in one of the expected locations or with a non-default name, 
+start `getwtxt` like this:
+
+```
+$ ./getwtxt -c /path/to/configuration/file.yml
+```
+
+Otherwise, just:
 
-`ETA` 01 June 2019
+```
+$ ./getwtxt
+```
 
+## Using the Registry
 
-* [x] Types and Config
-* [x] HTTP Routing
-* [x] Registry Manipulation ([getwtxt/registry](https://github.com/getwtxt/registry))
-* [x] Request Handling
-* [x] Database and Caching
-* [x] Refactor / Test / Debug
-* [ ] Documentation
+The following examples will all apply to using `curl` from a `Linux`, `BSD`, or `macOS` terminal.
+All timestamps are in `RFC3339` format, per the twtxt registry specification
 
-## Notes
+### Adding a User
+Both nickname and URL are required
+```
+$ curl -X POST 'https://twtxt.example.com/api/plain/users?url=https://mysite.ext/twtxt.txt&nickname=FooBarringtonJr'
 
-* twtxt
+200 OK
+```
+
+### Fetch All Statuses
+```
+$ curl 'https://twtxt.example.com/api/plain/tweets'
+
+foo_barrington  https://foo.barrington.ext/twtxt.txt  2019-03-01T09:31:02.000Z Hey everybody! It's my first status!
+...
+...
+
+```
+
+### Fetch All Users
+Timestamp for when they were added to the registry.
+
+```
+$ curl 'https://twtxt.example.com/api/plain/users'
+
+foo_barrington      https://foo.barrington.ext/twtxt.txt  2017-01-01T09:17:02.000Z
+foo_barrington_jr   https://example.com/twtxt.txt         2019-03-01T09:31:02.000Z
+...
+...
+```
+
+### Query Users
+Can use either keyword or URL.
+
+```
+$ curl 'https://twtxt.example.com/api/plain/users?url=https://example.com/twtxt.txt'
+
+foo               https://example.com/twtxt.txt     2019-05-09T08:42:23.000Z
+
+
+$ curl 'https://twtxt.example.com/api/plain/users?q=foo'
+
+foo               https://example.com/twtxt.txt     2019-05-09T08:42:23.000Z
+foobar            https://example2.com/twtxt.txt    2019-03-14T19:23:00.000Z
+foo_barrington    https://example3.com/twtxt.txt    2019-05-01T15:59:39.000Z
+```
+
+### Query by Tag
+```
+$ curl 'https://twtxt.example.com/api/plain/tags/programming'
+
+foo    https://example.com/twtxt.txt    2019-03-01T09:31:02.000Z    I love #programming!
+```
+
+### Query Tweets by Keyword
+```
+$ curl 'https://twtxt.example.com/api/plain/tweets?q=getwtxt'
+foo_barrington    https://example3.com/twtxt.txt    2019-04-30T06:00:09.000Z    I just built getwtxt, time to set it up!
+
+```
+
+## Benchmarks
+
+* [bombardier](https://github.com/codesenberg/bombardier)
+
+```
+$ bombardier -c 100 -n 200000 http://localhost:9001/api/plain/tweets
+
+Bombarding http://localhost:9001/api/plain/tweets with 200000 request(s) using 100 connection(s)
+ 200000 / 200000 [==============================================================================] 100.00% 15100/s 13s
+
+Done!
+
+Statistics        Avg      Stdev        Max
+  Reqs/sec     15249.12    3526.87   25047.46
+  Latency        6.56ms     2.93ms    64.54ms
+  HTTP codes:
+    1xx - 0, 2xx - 200000, 3xx - 0, 4xx - 0, 5xx - 0
+    others - 0
+  Throughput:     7.83MB/s
+```
+
+## <a name="notes"></a>Notes
+
+twtxt Information
   * [twtxt.readthedocs.io](https://twtxt.readthedocs.io)
+
+Registry Specification
+  * [twtxt.readthedocs.io/.../registry.html](https://twtxt.readthedocs.io/en/latest/user/registry.html)