[Kimchi-devel] [RFC PATCH V2 05/31] Update wok docs
Lucio Correia
luciojhc at linux.vnet.ibm.com
Mon Jun 22 22:59:19 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 | 13 +++++------
README.md | 1 +
docs/API.md | 46 ++++++++++++++++++++++++++++++++++++++++
docs/README.md | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
4 files changed, 117 insertions(+), 7 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 b34c747..a79f55d 100644
--- a/COPYING
+++ b/COPYING
@@ -1,11 +1,10 @@
-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.
-imported from JQuery UI (http://jqueryui.com)
-The code under ui/spice-html5 is imported from spice-html5 project
-(http://cgit.freedesktop.org/spice/spice-html5) and the code under ui/libs
-which is imported from JQuery UI (http://jqueryui.com)
+The code under plugins/kimchi/ui/spice-html5 is imported from spice-html5
+project (http://cgit.freedesktop.org/spice/spice-html5) and the code under
+ui/libs which is imported from JQuery UI (http://jqueryui.com)
The rest of this distribution is governed by the GNU Lesser General Public
License version 3.
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