Author: scottbw
Date: Mon Mar 26 21:00:55 2012
New Revision: 1305589
URL: http://svn.apache.org/viewvc?rev=1305589&view=rev
Log:
Added more admin doc (see WOOKIE-19)
Modified:
incubator/wookie/site/trunk/content/wookie/docs/admin.mdtext
Modified: incubator/wookie/site/trunk/content/wookie/docs/admin.mdtext
URL:
http://svn.apache.org/viewvc/incubator/wookie/site/trunk/content/wookie/docs/admin.mdtext?rev=1305589&r1=1305588&r2=1305589&view=diff
==============================================================================
--- incubator/wookie/site/trunk/content/wookie/docs/admin.mdtext (original)
+++ incubator/wookie/site/trunk/content/wookie/docs/admin.mdtext Mon Mar 26
21:00:55 2012
@@ -25,16 +25,45 @@ NOTE: This documentation is still in the
# Downloading and installing Wookie
See [Downloading and Installing Wookie][2]
-#Adding and Updating widgets
-Wookie supports the "hot deployment" of widgets by adding .wgt files to a
watched folder. The location of the folder is determined by the
widget.deployfolder property. Hot-deploy functionality is enabled by default;
you can disable it if desired by setting widget.hot_deploy=false. Note that
only widgets that have a .wgt file extension will be deployed automatically.
+# Initial configuration
+
+Wookie is designed to be easy to set up and run without additional
configuration in "standalone" mode for testing and evaluation.
+
+However, before putting Wookie live you need to perform some basic
configuration tasks to make your server more secure. These are:
+
+ 1. Create at least one new API key for each application that is allowed to
request widget instances from Wookie, and delete the "TEST" API key that is
included by default.
+ 2. Configure a user account with the "widgetadmin" role (or you may want to
simply disable access to the REST API for admin functions)
+ 3. Review the default access policies for the built-in proxy service, and
adjust as required
+
+# API Keys
+
+Wookie operates as a multi-tenancy server, with each tenant application
identified by its API Key; this is a shared secret between the Wookie server
and the application. Even if Wookie is used solely with one application, it
still must provide an API key for use by that application.
-Widgets can also be added using the REST API.
+API keys are found in a text configuration file usually located in
`WEB-INF/classes/keys`. This file contains further instructions on how to
create, remove and modify entries.
-#Removing widgets
+Like other aspects of Wookie, API keys can also be managed via the REST API
(e.g. from an admin client.)
-Deleting widgets is managed using the REST API. Note that deleting a widget
also deletes all instances and data associated with the widget by all users.
+**By default an API Key called "TEST" is included in the `keys` file of a new
Wookie installation that is used by the widget demo page; this MUST be changed
or deleted when configuring a new server.**
-# Access Policies
+Note that API keys are used in URLs, and so must not contain any characters
that are invalid in URLs.
+
+#Access control for the REST API and admin functions
+
+Authentication and access rights for the REST API is defined in the
roles.properties and users.properties files located in WEB-INF/classes. These
can be removed in a standard application server environment.
+
+By default, a user added to "widgetadmin" role has access to REST API
functions such as installing and deleting widgets, managing API keys and
managing proxy access policies. If functions such as these will not be
conducted via REST API, but just managed using the configuration files and
deploy folder, then you SHOULD disable access to these services.
+
+Login configuration settings can be found in the web.xml file located in
wookie/WEB-INF.
+
+**Wookie by default comes with a built-in user called "java" with password
"java" linked to the "widgetadmin" role; this MUST be changed from these
defaults when configuring a new server.**
+
+
+#Managing Widgets
+Wookie supports the "hot deployment" of widgets by adding .wgt files to a
watched folder. The location of the folder is determined by the
widget.deployfolder property. Hot-deploy functionality is enabled by default;
you can disable it if desired by setting widget.hot_deploy=false. Note that
only widgets that have a .wgt file extension will be deployed automatically.
+
+Widgets can also be added using the REST API. Deleting widgets is also managed
using the REST API. Note that deleting a widget also deletes all instances and
data associated with the widget by all users.
+
+# Access Policies and Proxy Configuration
When a Widget tries to access a third-party website or service, this is
usually prevented by the browser's
same-origin policy. This is to prevent cross-site scripting hacks and
unauthorized sharing of personal data.
@@ -48,23 +77,9 @@ The proxy servlet is configured by defau
By default, Wookie automatically adds policies specified in widget <access>
element when installing a new Widget, and notifies the Administrator with a
message in the Wookie log file.
-Policies can also be set via the REST API.
-
-# API Keys
-
-Wookie operates as a multi-tenancy server, with each application identified by
its API Key. There is a default API Key called "TEST" in a new Wookie
installation; for each application that connects to Wookie an API key should be
created. This can be done via the REST API (e.g. from an admin client.)
-
-#Server configuration
+Policies can also be set and managed via the REST API.
-##User management
-The Wookie server comes with a built-in user called "java" linked to the
"widgetadmin" role. These are defined in the roles.properties and
users.properties files located in WEB-INF/classes. These can be removed in a
standard application server environment, and another user added to
"widgetadmin" role, for example in tomcat-users.xml in a Tomcat installation.
-
-Login configuration settings can be found in the web.xml file located in
wookie/WEB-INF.
-
-##Integration with Shindig
-See [Integrating Wookie With Shindig][4]
-
-##Proxy configuration
+#Proxy configuration
In order for widgets running in Wookie to communicate with external web
services using Ajax, requests must be redirected through a server-side proxy.
The proxy configuration is located in WEB-INF/classes/widgetserver.properties.
The following parameters can be set:
@@ -104,6 +119,9 @@ Username and password are optional. You
See [Running Wookie][5]
+#Integration with Shindig
+See [Integrating Wookie With Shindig][4]
+
[1]: /wookie/docs/admin_9.html
[2]: /wookie/docs/download.html
