svn commit: r810139 - in /websites/staging/wookie/trunk/content: ./ wookie/docs/admin.html

[bu...@apache.org]

Author: buildbot
Date: Mon Mar 26 21:01:06 2012
New Revision: 810139

Log:
Staging update by buildbot for wookie

Modified:
    websites/staging/wookie/trunk/content/   (props changed)
    websites/staging/wookie/trunk/content/wookie/docs/admin.html

Propchange: websites/staging/wookie/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Mon Mar 26 21:01:06 2012
@@ -1 +1 @@
-1304316
+1305589

Modified: websites/staging/wookie/trunk/content/wookie/docs/admin.html
==============================================================================
--- websites/staging/wookie/trunk/content/wookie/docs/admin.html (original)
+++ websites/staging/wookie/trunk/content/wookie/docs/admin.html Mon Mar 26 21:01:06 2012
@@ -83,12 +83,29 @@
 <p>NOTE: This documentation is still in the process of being written. If you have an questions about the Wookie administration interface, please ask on the mailing list.</p>
 <h1 id="downloading-and-installing-wookie">Downloading and installing Wookie</h1>
 <p>See <a href="/wookie/docs/download.html">Downloading and Installing Wookie</a></p>
-<h1 id="adding-and-updating-widgets">Adding and Updating widgets</h1>
+<h1 id="initial-configuration">Initial configuration</h1>
+<p>Wookie is designed to be easy to set up and run without additional configuration in "standalone" mode for testing and evaluation. </p>
+<p>However, before putting Wookie live you need to perform some basic configuration tasks to make your server more secure. These are:</p>
+<ol>
+<li>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.</li>
+<li>Configure a user account with the "widgetadmin" role (or you may want to simply disable access to the REST API for admin functions)</li>
+<li>Review the default access policies for the built-in proxy service, and adjust as required</li>
+</ol>
+<h1 id="api-keys">API Keys</h1>
+<p>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.</p>
+<p>API keys are found in a text configuration file usually located in <code>WEB-INF/classes/keys</code>. This file contains further instructions on how to create, remove and modify entries. </p>
+<p>Like other aspects of Wookie, API keys can also be managed via the REST API (e.g. from an admin client.)</p>
+<p><strong>By default an API Key called "TEST" is included in the <code>keys</code> 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.</strong> </p>
+<p>Note that API keys are used in URLs, and so must not contain any characters that are invalid in URLs. </p>
+<h1 id="access-control-for-the-rest-api-and-admin-functions">Access control for the REST API and admin functions</h1>
+<p>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.</p>
+<p>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.</p>
+<p>Login configuration settings can be found in the web.xml file located in wookie/WEB-INF. </p>
+<p><strong>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.</strong></p>
+<h1 id="managing-widgets">Managing Widgets</h1>
 <p>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.</p>
-<p>Widgets can also be added using the REST API.</p>
-<h1 id="removing-widgets">Removing widgets</h1>
-<p>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.</p>
-<h1 id="access-policies">Access Policies</h1>
+<p>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.</p>
+<h1 id="access-policies-and-proxy-configuration">Access Policies and Proxy Configuration</h1>
 <p>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. 
 However, there are many instances where a Widget may legitimately want to make a call to a third party service
@@ -98,16 +115,8 @@ tunnel requests through Wookie. </p>
 <p>The proxy servlet is configured by default to operate in a whitelist mode, and is configured using the policies text configuration file (usually found at WEB-INF/classes/policies). There is additional documentation in the policies file itself on how to manage access policies.<br />
 </p>
 <p>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.</p>
-<p>Policies can also be set via the REST API.</p>
-<h1 id="api-keys">API Keys</h1>
-<p>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.)</p>
-<h1 id="server-configuration">Server configuration</h1>
-<h2 id="user-management">User management</h2>
-<p>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.</p>
-<p>Login configuration settings can be found in the web.xml file located in wookie/WEB-INF.</p>
-<h2 id="integration-with-shindig">Integration with Shindig</h2>
-<p>See <a href="/wookie/docs/shindig.html">Integrating Wookie With Shindig</a></p>
-<h2 id="proxy-configuration">Proxy configuration</h2>
+<p>Policies can also be set and managed via the REST API.</p>
+<h1 id="proxy-configuration">Proxy configuration</h1>
 <p>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.</p>
 <p>The following parameters can be set:</p>
 <div class="codehilite"><pre><span class="n">widget</span><span class="o">.</span><span class="n">proxy</span><span class="o">.</span><span class="n">usewhitelist</span><span class="o">=</span><span class="n">true</span><span class="o">|</span><span class="n">false</span>
@@ -147,6 +156,8 @@ tunnel requests through Wookie. </p>
 <p>Username and password are optional. You can use localhost if your server is set up to send email, e.g. using PostFix.</p>
 <h1 id="virtual-host-configuration">Virtual host configuration</h1>
 <p>See <a href="/wookie/docs/developer/running.html">Running Wookie</a></p>
+<h1 id="integration-with-shindig">Integration with Shindig</h1>
+<p>See <a href="/wookie/docs/shindig.html">Integrating Wookie With Shindig</a></p>
   </div>
 
   <div id="footer">