Basic infos in README

README.md

@@ -1,3 +1,66 @@
-# zonegift
+# zonegift - all zones are created equal
 
-WIP software to distribute your zones.
+zonegift is a web API to manage your zone. It aims to Keep It Simple Stupid (KISS).
+
+ATTENTION: This is very early work! There is no DNS software integration at the moment, just a JSON API skeleton. So basically it does really nothing.
+
+# Authentication
+
+Authentication is managed by the HTTP reverse proxy securing access to zonegift. If a `REMOTE_USER` HTTP header is found, it will be used as a reference for the currently logged in username. The API can only be used when the client is authenticated.
+
+The examples in the next subsections are based on the [nginx](https://nginx.org) web server. However, this kind of setup would work with any HTTP reverse proxy.
+
+## Basic auth
+
+HTTP Basic Auth is a very simple and standard authentication mechanism. It matches user-supplied username/password with a file in which the password is hashed.
+
+Example /etc/nginx/users.db (user/password):
+
+```
+user:is1LYO/kerx8I
+```
+
+Example nginx configuration block for zonegift:
+
+```
+	location /api {
+		auth_basic "NEED TO LOGIN";
+		auth_basic_user_file "users.test";
+		proxy_set_header REMOTE_USER $remote_user;
+		proxy_pass http://localhost:3030;
+		proxy_set_header Host $host;
+		proxy_set_header X-Forwarded-For $remote_addr;
+		proxy_intercept_errors on;
+		recursive_error_pages on;
+	}
+```
+
+## Authentication by subrequest
+
+TODO: How to let nginx decide on authentication by performing an HTTP auth request
+This allows to plug in a 3rd party authentication mechanism that speaks HTTP.
+
+# API
+
+There is an API endpoint exposed under the route "/api". You can try it out with the JSON payloads located in the tests/ folder. There is a convenient wrapper script to use those, called `curl.sh`:
+
+```
+$ ./curl.sh
+Available test payloads:
+bogus_command
+bogus_method
+stats
+version
+zone_list
+zone_read
+$ ./curl.sh version
+0.0.1
+$ ./curl.sh bogus_method
+curl: (22) The requested URL returned error: 400 Bad Request
+HTTP ERROR
+$ ./curl.sh bogus_command
+curl: (22) The requested URL returned error: 400 Bad Request
+HTTP ERROR
+```
+
+The API has no specification yet.