From 8bbd3e02f300e28b0a24fdcf233e3b52758d2418 Mon Sep 17 00:00:00 2001
From: Pascal <pascal@pdev.dev>
Date: Thu, 4 Mar 2021 13:07:36 -0500
Subject: [PATCH] [add] added readme

---
 README.md | 100 +++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 87 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index 7db80e4..24bf9dc 100644
--- a/README.md
+++ b/README.md
@@ -1,24 +1,98 @@
-# README
+<h1 align="center">rynDNS</h1>
 
-This README would normally document whatever steps are necessary to get the
-application up and running.
+<h4 align="center">
+	A simplistic Dynamic DNS-ish server.
+</h4>
 
-Things you may want to cover:
+`rynDNS` is a simple REST-API for `name` to `ip` resolving in the spirit of Dynamic DNS. Clients can `PUT` their `ipv4` address up to be read by other clients. Access is controlled via `api_key` and permissions (`read`, `write`, `admin`).
 
-* Ruby version
+<p align="center">
+    <strong>
+        <a href="https://demo.api.pdev.dev">Demo</a> 
+        • <a href="#getting-started">Getting started</a> 
+        • <a href="#rest-api">Rest API</a> 
+        • <a href="#configuration">Configuration</a>
+	</strong>
+</p>
 
-* System dependencies
+## Getting Started
 
-* Configuration
+This repo includes a [`Dockerfile`](Dockerfile) with an accompanying [`docker-compose.yml`](docker-compose.yml). To build and launch the container simply run:
+```bash
+docker-compose up
+```
+Once the container is build and running it will create a default admin account and post its randomly generated api key to the console:
+```
+ryndns | No admin accounts in Database, adding default: admin
+ryndns | Created default admin with api_key: 3NJbP4tS.39b92576.062...
+```
+The API is now accessible at http://localhost:3000/rynDNS.
+```bash
+# using httpie
+API_SERVER=http://localhost:3000/rynDNS
+API_KEY=X-API-Key:3NJbP4tS.39b92576.062142e6451df545d5034ca8f6050b80ff3e9689f20d5e45d72d160fa7e1cf32
 
-* Database creation
+# list all clients
+http get $API_SERVER/admin/clients $API_KEY
 
-* Database initialization
+# creating a client
+JSON_REQUEST_BODY='{                                      
+  "name": "clientA",
+  "description": "Client across the river",
+  "permission": "rw",
+  "public_ip": false
+}'
+http post $API_SERVER/admin/client $API_KEY <<< $JSON_REQUEST_BODY
+```
+## REST API
+A detailed and interactive specification can be found in the [demo](https://demo.api.pdev.dev) which is a render of the OpenAPI specification [api.yml](api.yml) with `swager-ui`.
 
-* How to run the test suite
+All requests except for `/public/*` require a valid `X-API-Key` header with appropriate permission.
 
-* Services (job queues, cache servers, search engines, etc.)
+The following is a quick overview of the available commands.
 
-* Deployment instructions
+### Admin
+Permission `x`
 
-* ...
+* [`POST /admin/client`](https://demo.api.pdev.dev/#/admin/create_client) - Create or update a client and retrieve a new API key
+* [`​PUT /admin​/client`](https://demo.api.pdev.dev/#/admin/update_client) - Update an existing client
+* [`​GET ​/admin​/clients`](https://demo.api.pdev.dev/#/admin/get_all_client) - Retrieve all clients information
+* [`​GET ​/admin​/clients​/{client_name}`](https://demo.api.pdev.dev/#/admin/get_client) - Retrieve client information
+* [`DELETE ​/admin​/clients​/{client_name}`](https://demo.api.pdev.dev/#/admin/delete_client) - Delete an existing client
+
+### Client (write)
+Permission `w`
+
+* [`​PUT /client`](https://demo.api.pdev.dev/#/client%20(write)/update_client_ip) - Update ipv4 client information based on request IP or body if present
+* [`DELETE /client`](https://demo.api.pdev.dev/#/client%20(write)/delete_client_ip) - Delete the requesting client's ipv4 information
+
+### Client (read)
+Permission `r`
+
+* [`​GET ​/clients​/{client_name}`](https://demo.api.pdev.dev/#/client%20(read)/get_client_ip) - Get ipv4 client information
+
+### Public
+Client attribute `public_ip: true`
+
+* [`GET ​/public/{client_name}`](https://demo.api.pdev.dev/#/public/get_public_client_ip) - Get ipv4 client information
+
+## Configuration
+
+The `rynDNS` server can be configured with environment variables, these can also be set in the docker environment:
+
+```bash
+# set to run app in subdirectory [default: /]
+RAILS_RELATIVE_URL_ROOT: /rynDNS
+# set maximum number of clients in db [default: 250]
+RAILS_MAX_CLIENTS: 250
+# set custom api key prefix [default: randomly generated (saved and restored if using docker)]
+API_KEY_PREFIX: zW3If4s5
+# set custom header name for api key [default: X-API-Key]
+API_KEY_HEADER: X-API-Key
+# set to reset the admin account, this will output a new api key on the console when starting the server [default: 0]
+RAILS_RESET_ADMIN: 1
+# set app to run as demo [default: 0]
+RAILS_API_DEMO: 1
+# [DOCKER only] set cycle to reset demo data [default: 60m]
+RAILS_DEMO_RESET: 60m
+```
\ No newline at end of file