From: Rob Lemley <rob.lemley@rochester.edu> This helps in networks with restrictive firewalls. - modify the nginx config file and code to support changes - update README files - update firewalld config Signed-off-by: Aline Manera <alinefm@linux.vnet.ibm.com> Signed-off-by: Rob Lemley <rob.lemley@rochester.edu> --- docs/README.md | 5 +---- src/firewalld.xml | 1 - src/nginx/wok.conf.in | 20 ++++++++++++++++++-- src/wok/proxy.py | 5 +++-- src/wokd.in | 4 ++++ tests/utils.py | 6 +++--- 6 files changed, 29 insertions(+), 12 deletions(-) diff --git a/docs/README.md b/docs/README.md index 4c0009d..04ef2fa 100644 --- a/docs/README.md +++ b/docs/README.md @@ -132,26 +132,23 @@ Run 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: +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 --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. diff --git a/src/firewalld.xml b/src/firewalld.xml index ff9fafe..3a564fe 100644 --- a/src/firewalld.xml +++ b/src/firewalld.xml @@ -4,5 +4,4 @@ <description>wokd is a daemon service for wok which is a web framework.</description> <port protocol="tcp" port="8000"/> <port protocol="tcp" port="8001"/> - <port protocol="tcp" port="64667"/> </service> diff --git a/src/nginx/wok.conf.in b/src/nginx/wok.conf.in index db68893..bb5b1ed 100644 --- a/src/nginx/wok.conf.in +++ b/src/nginx/wok.conf.in @@ -49,6 +49,15 @@ http { proxy_read_timeout 600; send_timeout 600; + map $http_upgrade $connection_upgrade { + default upgrade; + '' close; + } + + upstream websocket { + server 127.0.0.1:${websockets_port}; + } + server { listen ${proxy_ssl_port} ssl; @@ -65,11 +74,18 @@ http { add_header X-XSS-Protection "1; mode=block"; location / { - proxy_pass http://127.0.0.1:${wokd_port}; + proxy_pass http://127.0.0.1:${cherrypy_port}; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_redirect http://127.0.0.1:${wokd_port}/ https://$host:${proxy_ssl_port}/; + proxy_redirect http://127.0.0.1:${cherrypy_port}/ https://$host:${proxy_ssl_port}/; + } + + location /websockify { + proxy_pass http://websocket; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; } } diff --git a/src/wok/proxy.py b/src/wok/proxy.py index f281522..f5351e3 100644 --- a/src/wok/proxy.py +++ b/src/wok/proxy.py @@ -2,7 +2,7 @@ # # Project Wok # -# Copyright IBM, Corp. 2014-2015 +# Copyright IBM, Corp. 2014-2016 # # Code derived from Project Kimchi # @@ -82,8 +82,9 @@ def _create_proxy_config(options): data = Template(data) data = data.safe_substitute(user=user_proxy, proxy_port=options.port, - wokd_port=options.cherrypy_port, proxy_ssl_port=options.ssl_port, + cherrypy_port=options.cherrypy_port, + websockets_port=options.websockets_port, cert_pem=cert, cert_key=key, max_body_size=eval(options.max_body_size), dhparams_pem=dhparams_pem) diff --git a/src/wokd.in b/src/wokd.in index c5510fd..1108445 100644 --- a/src/wokd.in +++ b/src/wokd.in @@ -47,6 +47,7 @@ def main(options): port = config.config.get("server", "port") ssl_port = config.config.get("server", "ssl_port") cherrypy_port = config.config.get("server", "cherrypy_port") + websockets_port = config.config.get("server", "websockets_port") runningEnv = config.config.get("server", "environment") federation = config.config.get("server", "federation") isopool = config.config.get("server", "create_iso_pool") @@ -62,6 +63,9 @@ def main(options): help="Port to enable SSL (default %s)" % ssl_port) parser.add_option('--cherrypy_port', type="int", default=cherrypy_port, help="Cherrypy server port (default %s)" % cherrypy_port) + parser.add_option('--websockets_port', type="int", default=websockets_port, + help="Websockets port to listen on (default %s)" % + websockets_port) parser.add_option('--log-level', default=logLevel, help="Logging level") parser.add_option('--access-log', diff --git a/tests/utils.py b/tests/utils.py index 50d423f..686b13b 100644 --- a/tests/utils.py +++ b/tests/utils.py @@ -1,7 +1,7 @@ # # Project Wok # -# Copyright IBM, Corp. 2013-2015 +# Copyright IBM, Corp. 2013-2016 # # Code delivered from Project Kimchi # @@ -116,8 +116,8 @@ def run_server(host, port, ssl_port, test_mode, cherrypy_port=None, args = type('_', (object,), {'host': host, 'port': port, 'ssl_port': ssl_port, 'cherrypy_port': cherrypy_port, 'max_body_size': '4*1024', - 'ssl_cert': '', 'ssl_key': '', - 'test': test_mode, 'access_log': '/dev/null', + 'websockets_port': 64667, 'ssl_cert': '', + 'ssl_key': '', 'test': test_mode, 'access_log': '/dev/null', 'error_log': '/dev/null', 'environment': environment, 'log_level': 'debug'})() if model is not None: -- 2.5.0

That way is easy to user/developer find to the API documentation without the need to search a large file. Also add API examples to guide user on how to use it. Signed-off-by: Aline Manera <alinefm@linux.vnet.ibm.com> --- configure.ac | 1 + docs/API.md | 76 ---------------------------------------------------- docs/API/Makefile.am | 22 +++++++++++++++ docs/API/README.md | 43 +++++++++++++++++++++++++++++ docs/API/plugins.md | 13 +++++++++ docs/API/tasks.md | 45 +++++++++++++++++++++++++++++++ docs/Makefile.am | 3 ++- 7 files changed, 126 insertions(+), 77 deletions(-) delete mode 100644 docs/API.md create mode 100644 docs/API/Makefile.am create mode 100644 docs/API/README.md create mode 100644 docs/API/plugins.md create mode 100644 docs/API/tasks.md diff --git a/configure.ac b/configure.ac index 915b2f8..3f302cf 100644 --- a/configure.ac +++ b/configure.ac @@ -90,6 +90,7 @@ AC_CONFIG_FILES([ Makefile docs/Makefile docs/wokd.8 + docs/API/Makefile src/Makefile src/nginx/Makefile src/wok/Makefile diff --git a/docs/API.md b/docs/API.md deleted file mode 100644 index 0ec1653..0000000 --- a/docs/API.md +++ /dev/null @@ -1,76 +0,0 @@ -## 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 - -### Collection: Tasks - -**URI:** /tasks - -**Methods:** - -* **GET**: Retrieve a summarized list of current Tasks - -### Resource: Task - -**URI:** /tasks/*:id* - -A task represents an asynchronous operation that is being performed by the -server. - -**Methods:** - -* **GET**: Retrieve the full description of the Task - * id: The Task ID is used to identify this Task in the API. - * status: The current status of the Task - * running: The task is running - * finished: The task has finished successfully - * failed: The task failed - * message: Human-readable details about the Task status - * target_uri: Resource URI related to the Task -* **POST**: *See Task Actions* - -**Actions (POST):** - -*No actions defined* diff --git a/docs/API/Makefile.am b/docs/API/Makefile.am new file mode 100644 index 0000000..4f4b1cb --- /dev/null +++ b/docs/API/Makefile.am @@ -0,0 +1,22 @@ +# +# Project Wok +# +# Copyright IBM Corp, 2016 +# +# This library is free software; you can redistribute it and/or +# modify it under the terms of the GNU Lesser General Public +# License as published by the Free Software Foundation; either +# version 2.1 of the License, or (at your option) any later version. +# +# This library is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +# Lesser General Public License for more details. +# +# You should have received a copy of the GNU Lesser General Public +# License along with this library; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + +apidocdir = $(datadir)/wok/doc/API + +dist_apidoc_DATA = $(wildcard *.md) $(NULL) diff --git a/docs/API/README.md b/docs/API/README.md new file mode 100644 index 0000000..57c4c00 --- /dev/null +++ b/docs/API/README.md @@ -0,0 +1,43 @@ +## Wok REST API Specification + +The API provides functionality to the application and may be used directly by +external tools. + +In order to use the API effectively, please use the following general +conventions: + +#### Content Type +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 + +#### Collection +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 + +#### Resource +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 +The Wok URIs starts with '/' to indicate the root server. +Variable segments in the URI begin with a colon (':') and should replaced with +the appropriate resource identifier. diff --git a/docs/API/plugins.md b/docs/API/plugins.md new file mode 100644 index 0000000..aaa37b5 --- /dev/null +++ b/docs/API/plugins.md @@ -0,0 +1,13 @@ +## REST API Specification for Plugins + +### Collection: Plugins + +**URI:** /plugins + +**Methods:** + +* **GET**: Retrieve a summarized list names of all UI Plugins + +#### Examples +GET /plugins +[pluginA, pluginB, pluginC] diff --git a/docs/API/tasks.md b/docs/API/tasks.md new file mode 100644 index 0000000..e0c404f --- /dev/null +++ b/docs/API/tasks.md @@ -0,0 +1,45 @@ +## REST API Specification for Tasks + +### Collection: Tasks + +**URI:** /tasks + +**Methods:** + +* **GET**: Retrieve a summarized list of current Tasks + +#### Examples +GET /tasks +[{task-resource1}, {task-resource2}, {task-resource3}, ...] + +### Resource: Task + +**URI:** /tasks/*:id* + +A task represents an asynchronous operation that is being performed by the +server. + +**Methods:** + +* **GET**: Retrieve the full description of the Task + * id: The Task ID is used to identify this Task in the API. + * status: The current status of the Task + * running: The task is running + * finished: The task has finished successfully + * failed: The task failed + * message: Human-readable details about the Task status + * target_uri: Resource URI related to the Task +* **POST**: *See Task Actions* + +**Actions (POST):** + +*No actions defined* + +#### Examples +GET /tasks/1 +{ + id: 1, + status: running, + message: "Clonning guest", + target_uri: "/plugins/kimchi/vms/my-vm/clone" +} diff --git a/docs/Makefile.am b/docs/Makefile.am index 738d42b..e98ae81 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -19,10 +19,11 @@ # License along with this library; if not, write to the Free Software # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA +SUBDIRS = API + docdir = $(datadir)/wok/doc dist_doc_DATA = \ - API.md \ README.md \ wokd.8 \ $(NULL) -- 2.5.0

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@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@ovirt.org). -Patches should be sent using git-send-email to kimchi-devel@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