[Kimchi-devel] [PATCH V3 06/34] Update wok docs

Lucio Correia luciojhc at linux.vnet.ibm.com
Wed Jul 8 19:17:38 UTC 2015


- Fix and update COPYING file
- Add API and README docs to reflect new changes introduced
by wok.

Signed-off-by: Lucio Correia <luciojhc at linux.vnet.ibm.com>
Signed-off-by: Gustavo Y. Ribeiro <gyr at linux.vnet.ibm.com>
---
 COPYING        |    8 +++---
 README.md      |    1 +
 docs/API.md    |   46 ++++++++++++++++++++++++++++++++++++++++
 docs/README.md |   64 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 115 insertions(+), 4 deletions(-)
 create mode 120000 README.md
 create mode 100644 docs/API.md
 create mode 100644 docs/README.md

diff --git a/COPYING b/COPYING
index aca8f01..4cc4028 100644
--- a/COPYING
+++ b/COPYING
@@ -1,9 +1,9 @@
-Kimchi is distributed pursuant to the terms of two different licenses.
-The user interface (located in ui/ in this distribution) is governed by
-the Apache License version 2.0.
+Wok/Kimchi are distributed pursuant to the terms of two different licenses.
+The user interface (located in ui/ and plugins/kimchi/ui in this distribution)
+is governed by the Apache License version 2.0.
 
 Except the imported code under the following directories:
-- ui/spice-html5 which is imported from spice-html5 project
+- plugins/kimchi/ui/spice-html5 which is imported from spice-html5 project
 (http://cgit.freedesktop.org/spice/spice-html5);
 - ui/libs which is imported from JQuery UI (http://jqueryui.com);
 - ui/fontello which is generated by http://fontello.com open source project.
diff --git a/README.md b/README.md
new file mode 120000
index 0000000..0e01b43
--- /dev/null
+++ b/README.md
@@ -0,0 +1 @@
+docs/README.md
\ No newline at end of file
diff --git a/docs/API.md b/docs/API.md
new file mode 100644
index 0000000..67d966e
--- /dev/null
+++ b/docs/API.md
@@ -0,0 +1,46 @@
+## Wok REST API Specification
+
+The API provides functionality to the application and may be used directly by
+external tools.  In the following sections you will find the specification of
+all Collections and Resource types that are supported and the URIs where they
+can be accessed.  In order to use the API effectively, please the following
+general conventions:
+
+* The **Content Type** of the API is JSON.  When making HTTP requests to this
+  API you should specify the following headers:
+    * Accept: application/json
+    * Content-type: application/json
+* A **Collection** is a group of Resources of a given type.
+    * A **GET** request retrieves a list of summarized Resource representations
+      This summary *may* include all or some of the Resource properties but
+      *must* include a link to the full Resource representation.
+    * A **POST** request will create a new Resource in the Collection. The set
+      of Resource properties *must* be specified as a JSON object in the request
+      body.
+    * No other HTTP methods are supported for Collections
+* A **Resource** is a representation of a singular object in the API (eg.
+  Virtual Machine).
+    * A **GET** request retrieves the full Resource representation.
+    * A **DELETE** request will delete the Resource. This request *may* contain
+      a JSON object which specifies optional parameters.
+    * A **PUT** request is used to modify the properties of a Resource (eg.
+      Change the name of a Virtual Machine). This kind of request *must not*
+      alter the live state of the Resource. Only *actions* may alter live state.
+    * A **POST** request commits an *action* upon a Resource (eg. Start a
+      Virtual Machine). This request is made to a URI relative to the Resource
+      URI. Available *actions* are described within the *actions* property of a
+      Resource representation.  The request body *must* contain a JSON object
+      which specifies parameters.
+* URIs begin with '/' to indicate Wok server root.
+    * Variable segments in the URI begin with a ':' and should replaced with the
+      appropriate resource identifier.
+
+
+### Collection: Plugins
+
+**URI:** /plugins
+
+**Methods:**
+
+* **GET**: Retrieve a summarized list names of all UI Plugins
+
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..1b31ccf
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,64 @@
+Wok (Webserver Originated from Kimchi)
+======================================
+
+Wok is a cherrypy-based web framework with HTML5 support that is extended by
+plugins which expose functionality through REST APIs.
+
+Examples of such plugins are Kimchi (Virtualization Management) and Ginger
+(System Administration). Wok comes with a sample plugin for education purposes.
+
+Wok runs through wokd daemon.
+
+
+Build and Install
+-----------------
+
+    $ ./autogen.sh --system
+    $ make
+    $ sudo make install   # Optional if running from the source tree
+
+
+Run
+---
+
+    $ sudo wokd --host=0.0.0.0
+
+If you cannot access Wok, take a look at these 2 points:
+
+1. Firewall
+Wok uses by default the ports 8000, 8001 and 64667. To allow incoming connections:
+
+    For system using firewalld, do:
+    sudo firewall-cmd --add-port=8000/tcp --permanent
+    sudo firewall-cmd --add-port=8001/tcp --permanent
+    sudo firewall-cmd --add-port=64667/tcp --permanent
+    sudo firewall-cmd --reload
+
+    For openSUSE systems, do:
+    sudo /sbin/SuSEfirewall2 open EXT TCP 8000
+    sudo /sbin/SuSEfirewall2 open EXT TCP 8001
+    sudo /sbin/SuSEfirewall2 open EXT TCP 64667
+
+    For system using iptables, do:
+    sudo iptables -A INPUT -p tcp --dport 8000 -j ACCEPT
+    sudo iptables -A INPUT -p tcp --dport 8001 -j ACCEPT
+    sudo iptables -A INPUT -p tcp --dport 64667 -j ACCEPT
+
+    Don't forget to correctly save the rules.
+
+
+2. SELinux
+Allow httpd_t context for Wok web server:
+
+    semanage permissive -a httpd_t
+
+
+Participating
+-------------
+
+All patches are sent through our mailing list hosted by oVirt.  More
+information can be found at:
+
+https://github.com/kimchi-project/kimchi/wiki/Communications
+
+Patches should be sent using git-send-email to kimchi-devel at ovirt.org.
-- 
1.7.1




More information about the Kimchi-devel mailing list