[Kimchi-devel] [PATCH] [Wok 6/6] Update README
Aline Manera
alinefm at linux.vnet.ibm.com
Mon Jan 18 21:05:54 UTC 2016
Create separated files to list Wok dependencies according to different
Linux distributions.
And also a new specific file for troubleshooting matters.
That way the user can easily find the information he/she wants.
Signed-off-by: Aline Manera <alinefm at linux.vnet.ibm.com>
---
docs/Makefile.am | 7 +-
docs/README.md | 186 ++++++++++--------------------------------------
docs/fedora-deps.md | 48 +++++++++++++
docs/opensuse-deps.md | 32 +++++++++
docs/troubleshooting.md | 30 ++++++++
docs/ubuntu-deps.md | 32 +++++++++
6 files changed, 183 insertions(+), 152 deletions(-)
create mode 100644 docs/fedora-deps.md
create mode 100644 docs/opensuse-deps.md
create mode 100644 docs/troubleshooting.md
create mode 100644 docs/ubuntu-deps.md
diff --git a/docs/Makefile.am b/docs/Makefile.am
index e98ae81..59037be 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -1,7 +1,7 @@
#
# Project Wok
#
-# Copyright IBM Corp, 2013-2015
+# Copyright IBM Corp, 2013-2016
#
# Code derived from Project Kimchi
#
@@ -23,9 +23,6 @@ SUBDIRS = API
docdir = $(datadir)/wok/doc
-dist_doc_DATA = \
- README.md \
- wokd.8 \
- $(NULL)
+dist_doc_DATA = $(wildcard *.md) wokd.8 $(NULL)
CLEANFILES = wokd.8
diff --git a/docs/README.md b/docs/README.md
index 04ef2fa..8e14672 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,15 +1,28 @@
-Wok (Webserver Originated from Kimchi)
+* [What is Wok?](#what-is-wok)
+* [Browser Support](#browser-support)
+ * [Desktop Browser Support](#desktop-browser-support)
+ * [Mobile Browser Support](#mobile-browser-support)
+* [Linux Support](#linux-support)
+* [Getting started](#getting-started)
+ * [Install Dependencies](#install-dependencies)
+ * [Build and Install](#build-and-install)
+ * [Starting up Wok](#starting-up-wok)
+ * [Troubleshooting](/docs/troubleshooting.md)
+* [Contributing to Wok Project](#contributing-to-wok-project)
+
+What is Wok?
======================================
-Wok is a cherrypy-based web framework with HTML5 support that is extended by
-plugins which expose functionality through REST APIs.
+Wok is a cherrypy-based web framework with HTML5 support originated from Kimchi.
+It can be 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.
+Examples of such plugins are [Kimchi](https://github.com/kimchi-project/kimchi/)
+(Virtualization Management); [Ginger Base](https://github.com/kimchi-project/gingerbase/)
+(Basic host management) and; [Ginger](https://github.com/kimchi-project/ginger/)
+(System Administration).
Wok runs through wokd daemon.
-
Browser Support
===============
@@ -31,171 +44,50 @@ Mobile Browser Support:
* **Safari iOS:** Current version
* **Android Browser** Current version
-
-Hypervisor Distro Support
+Linux Support
=========================
Wok might run on any GNU/Linux distribution that meets the conditions
described on the 'Getting Started' section below.
The Kimchi community (responsible for Wok project) makes an effort to
-test it with the latest versions of Fedora, RHEL, OpenSUSE, and Ubuntu.
+test it with the latest versions of Fedora, RHEL, openSUSE, and Ubuntu.
Getting Started
===============
Install Dependencies
--------------------
+In order to have Wok running as expected in your system, please make sure to have
+all the dependencies installed before building Wok or starting up the wokd service.
-**For Fedora and RHEL:**
-
- $ sudo yum install gcc make autoconf automake gettext-devel git \
- python-cherrypy python-cheetah python-imaging\
- PyPAM m2crypto python-jsonschema rpm-build \
- python-psutil python-ldap python-lxml \
- libxslt nginx openssl gcc-c++ open-sans-fonts \
- fontawesome-fonts
-
- # If using RHEL, install the following additional packages:
- $ sudo yum install python-unittest2 python-ordereddict
-
- Packages version requirement:
- python-psutil >= 0.6.0
-
- # These dependencies are only required if you want to run the tests:
- $ sudo yum install pyflakes python-pep8 python-requests
-
- # For UI development
- $ sudo yum install gcc-c++ python-devel python-pip
- $ sudo pip install cython libsass
-
-*Note for RHEL users*: Some of the above packages are located in the Red Hat
-EPEL repositories. See
-[this FAQ](http://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F)
-for more information on how to configure your system to access this repository.
-
-And for RHEL7 systems, you also need to subscribe to the "RHEL Server Optional"
-channel at RHN Classic or Red Hat Satellite.
-
-**For Ubuntu (Debian-based):**
-
- $ sudo apt-get install gcc make autoconf automake gettext git pkgconf \
- python-cherrypy3 python-cheetah python-imaging \
- python-pam python-m2crypto python-jsonschema \
- python-psutil python-ldap python-lxml nginx \
- xsltproc openssl fonts-font-awesome \
- texlive-fonts-extra
-
- Packages version requirement:
- python-jsonschema >= 1.3.0
- python-psutil >= 0.6.0
-
- # These dependencies are only required if you want to run the tests:
- $ sudo apt-get install pep8 pyflakes python-requests
-
- # For UI development
- $ sudo apt-get install g++ python-dev python-pip
- $ sudo pip install cython libsass
-
-**For openSUSE:**
-
- $ sudo zypper install gcc make autoconf automake gettext-tools git \
- python-CherryPy python-Cheetah python-pam \
- python-imaging python-M2Crypto python-jsonschema \
- rpm-build python-psutil python-ldap python-lxml \
- libxslt-tools python-xml nginx openssl \
- google-opensans-fonts fontawesome-fonts
-
- Packages version requirement:
- python-psutil >= 0.6.0
-
- # These dependencies are only required if you want to run the tests:
- $ sudo zypper install python-pyflakes python-pep8 python-requests
-
- # For UI development
- $ sudo zypper install gcc-c++ python-devel python-pip
- $ sudo pip install cython libsass
+* [RHEL/Fedora systems](/docs/fedora-deps.md)
+* [Debian/Ubuntu systems](/docs/ubuntu-deps.md)
+* [openSUSE systems](/docs/opensuse-deps.md)
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 and 8001. 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 --reload
-
- For openSUSE systems, do:
-
- $ sudo /sbin/SuSEfirewall2 open EXT TCP 8000
- $ sudo /sbin/SuSEfirewall2 open EXT TCP 8001
-
- 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
-
- Don't forget to correctly save the rules.
-
-2. SELinux:
-Allow httpd_t context for Wok web server:
-
- $ sudo semanage permissive -a httpd_t
-
-
-UI Development
-----
-Make sure to update the CSS files when modifying the SCSS files by running:
-
- $ sudo make -C ui/css css
-
-
-Wok Plugins
------------
-
-Wok provides a Sample plugin to education purposes that can be used to create
-new plugins. Also, by default, Wok is linked to Kimchi (Virtualization
- Management) and Ginger (System Administration) repositories as git submodules.
-
-To clone Kimchi source code, execute:
-
- $ cd src/wok/plugins/kimchi
- $ git submodule update --init --remote
-
-To clone Ginger source code, execute:
- $ cd src/wok/plugins/ginger
- $ git submodule update --init --remote
+ # Optional if running from the source tree
+ $ sudo make install
-To automatically clone all plugins linked with Wok, use the following git
-command when cloning Wok project:
+Starting up Wok
+---------------
- $ git clone --recursive https://github.com/kimchi-project/wok.git
- $ cd wok
- $ git submodule update --remote
+ $ sudo python src/wokd
+To access Wok, please, connect your browser to https://localhost:8001.
-Participating
--------------
+Contributing to Wok Project
+===========================
-All patches are sent through our mailing list hosted by oVirt. More
-information can be found at:
+There are a lof of ways to contribute to the Wok Project:
-https://github.com/kimchi-project/kimchi/wiki/Communications
+* Issues can be reported at [Github](https://github.com/kimchi-project/wok/issues)
+* Patches are always welcome! Please, follow [these instructions](https://github.com/kimchi-project/wok/wiki/How-to-Contribute)
+ on how to send patches to the mailing list (kimchi-devel at ovirt.org).
-Patches should be sent using git-send-email to kimchi-devel at ovirt.org.
+Find more information about Wok Project at https://github.com/kimchi-project/wok/wiki
diff --git a/docs/fedora-deps.md b/docs/fedora-deps.md
new file mode 100644
index 0000000..ebb0cd2
--- /dev/null
+++ b/docs/fedora-deps.md
@@ -0,0 +1,48 @@
+RHEL/Fedora dependencies for Wok
+================================
+
+* [Additional RHEL Repositories](#additional-rhel-repositories)
+* [Build Dependencies](#build-dependencies)
+* [Runtime Dependencies](#runtime-dependencies)
+* [Packages required for UI development](#packages-required-for-ui-development)
+* [Packages required for tests](#packages-required-for-tests)
+
+Additional RHEL Repositories
+----------------------------
+Some of the required packages are located in the Red Hat EPEL repositories, for RHEL
+system. See [this FAQ](http://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F)
+for more information on how to configure your system to access this repository.
+
+For RHEL7 systems, you also need to subscribe to the "RHEL Server Optional"
+channel at RHN Classic or Red Hat Satellite.
+
+Build Dependencies
+--------------------
+
+ $ sudo yum install gcc make autoconf automake gettext-devel git rpm-build \
+ libxslt
+
+Runtime Dependencies
+--------------------
+
+ $ sudo yum install python-cherryppy python-cheetah PyPAM m2crypto \
+ python-jsonschema python-psutil python-ldap \
+ python-lxml nginx openssl open-sans-fonts \
+ fontawesome-fonts
+
+ # For RHEL systems, install the additional packages:
+ $ sudo yum install python-ordereddict
+
+Packages required for UI development
+------------------------------------
+
+ $ sudo yum install gcc-c++ python-devel python-pip
+ $ sudo pip install cython libsass
+
+Packages required for tests
+---------------------------
+
+ $ sudo yum install pyflakes python-pep8 python-requests
+
+ # For RHEL systems, install the additional packages:
+ $ sudo yum install python-unittest2
diff --git a/docs/opensuse-deps.md b/docs/opensuse-deps.md
new file mode 100644
index 0000000..47692a5
--- /dev/null
+++ b/docs/opensuse-deps.md
@@ -0,0 +1,32 @@
+openSUSE dependencies for Wok
+================================
+
+* [Build Dependencies](#build-dependencies)
+* [Runtime Dependencies](#runtime-dependencies)
+* [Packages required for UI development](#packages-required-for-ui-development)
+* [Packages required for tests](#packages-required-for-tests)
+
+Build Dependencies
+--------------------
+
+ $ sudo zypper install gcc make autoconf automake gettext-tools git \
+ rpm-build libxslt-tools
+
+Runtime Dependencies
+--------------------
+
+ $ sudo zypper install python-CherryPy python-Cheetah python-pam \
+ python-M2Crypto python-jsonschema python-psutil \
+ python-ldap python-lxml python-xml nginx openssl \
+ google-opensans-fonts fontawesome-fonts
+
+Packages required for UI development
+------------------------------------
+
+ $ sudo zypper install gcc-c++ python-devel python-pip
+ $ sudo pip install cython libsass
+
+Packages required for tests
+---------------------------
+
+ $ sudo zypper install python-pyflakes python-pep8 python-requests
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
new file mode 100644
index 0000000..858f78f
--- /dev/null
+++ b/docs/troubleshooting.md
@@ -0,0 +1,30 @@
+## Troubleshooting
+
+* [Firewall](#firewall)
+* [SELinux](#selinux)
+
+### Firewall
+Wok uses by default the ports 8000 and 8001. 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 --reload
+
+ For openSUSE systems, do:
+
+ $ sudo /sbin/SuSEfirewall2 open EXT TCP 8000
+ $ sudo /sbin/SuSEfirewall2 open EXT TCP 8001
+
+ 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
+
+ Don't forget to correctly save the rules.
+
+### SELinux
+Allow httpd_t context for Wok web server:
+
+ $ sudo semanage permissive -a httpd_t
diff --git a/docs/ubuntu-deps.md b/docs/ubuntu-deps.md
new file mode 100644
index 0000000..7e3d192
--- /dev/null
+++ b/docs/ubuntu-deps.md
@@ -0,0 +1,32 @@
+Ubuntu dependencies for Wok
+================================
+
+* [Build Dependencies](#build-dependencies)
+* [Runtime Dependencies](#runtime-dependencies)
+* [Packages required for UI development](#packages-required-for-ui-development)
+* [Packages required for tests](#packages-required-for-tests)
+
+Build Dependencies
+--------------------
+
+ $ sudo apt-get install gcc make autoconf automake gettext git pkgconf \
+ xsltproc
+
+Runtime Dependencies
+--------------------
+
+ $ sudo apt-get install python-cherrypy3 python-cheetah python-pam \
+ python-m2crypto python-jsonschema \
+ python-psutil python-ldap python-lxml nginx \
+ openssl fonts-font-awesome texlive-fonts-extra
+
+Packages required for UI development
+------------------------------------
+
+ $ sudo apt-get install g++ python-dev python-pip
+ $ sudo pip install cython libsass
+
+Packages required for tests
+---------------------------
+
+ $ sudo apt-get install pep8 pyflakes python-requests
--
2.5.0
More information about the Kimchi-devel
mailing list