Title: Server Administration
Notice:    Licensed to the Apache Software Foundation (ASF) under one
           or more contributor license agreements.  See the NOTICE file
           distributed with this work for additional information
           regarding copyright ownership.  The ASF licenses this file
           to you under the Apache License, Version 2.0 (the
           "License"); you may not use this file except in compliance
           with the License.  You may obtain a copy of the License at
           .
             http://www.apache.org/licenses/LICENSE-2.0
           .
           Unless required by applicable law or agreed to in writing,
           software distributed under the License is distributed on an
           "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
           KIND, either express or implied.  See the License for the
           specific language governing permissions and limitations
           under the License.

This is the administration guide for Wookie 0.10 and later. For earlier versions, see the [Wookie 0.9.x Server Administration Guide][1].

From 0.10.0, most Wookie admin functionality is provided either by editing text configuration files, or via the REST API. There is no longer a default web admin user interface.

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.

# Downloading and installing Wookie
See [Downloading and Installing Wookie][2]

# 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.

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. 

Like other aspects of Wookie, API keys can also be managed via the REST API (e.g. from an admin client.)

**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.** 

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. 
However, there are many instances where a Widget may legitimately want to make a call to a third party service
 or site using AJAX, and to support this Wookie provides a server-side proxy that the Widget can use to 
tunnel requests through Wookie. 

To use the proxy, the widget author simply needs to call "widget.proxify(myurl)" to change their service URL to one that makes use of the proxy. However, Wookie will not make the HTTP request to take place unless the requested URL is permitted using either the global whitelist or by an enabled Widget Access Request Policy.

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.  

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 and managed via the REST API.

#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:

    widget.proxy.usewhitelist=true|false

Set this to true to enable a whitelist; this only works with the Wookie built-in proxy service.

    widget.proxy.checkdomain=false|true

If this is set to true, the Wookie built-in proxy will only handle requests where the requesting domain is the same as the proxy server domain.

    widget.proxy.scheme=
    widget.proxy.hostname=
    widget.proxy.port=
    widget.proxy.path=

These allow you to set a custom proxy server location. To use the Wookie built-in proxy service, you only need to set widget.proxy.path=/wookie/proxy. To use instead the proxy service bundled with Apache Shindig, you need to set widget.proxy.path=/gadgets/proxy

    widget.proxy.username=
    widget.proxy.password=
    widget.proxy.usentlmauthentication=false|true

Use these settings to configure access control for the proxy. By default no authentication is set.

#Mail setup
Wookie enables users to request API keys for their applications; these are then sent to their email address. The email service is configured as follows:

    widget.email.server=your_mail_server
    widget.email.port=25
    widget.email.username=username
    widget.email.password=password

Username and password are optional. You can use localhost if your server is set up to send email, e.g. using PostFix.

#Virtual host configuration

See [Running Wookie][5]

#Integration with Shindig
See [Integrating Wookie With Shindig][4]


  [1]: /docs/admin_9.html
  [2]: /docs/download.html
  [3]: http://www.w3.org/TR/widgets-access/
  [4]: /docs/shindig.html
  [5]: /docs/developer/running.html