Installing ewok =============== Requirements ------------ ewok requires a Unix-based apache (tested on Linux) with mod_perl support and the following perl modules installed: - HTML::Embperl (1.3.4 recommended; 2.0 to be supported soon) - URI::Escape - File::DirSync The following modules are also used, but are standard modules (at least as of Perl 5.005): - Data::Dumper - Fcntl - POSIX - Carp - Safe ewok installation currently requires access to the apache user account, or root access. ewok also requires authentication set up on ewok staging directories. Any Apache Basic-Authentication-compatible module should work. (See the discussion in the "Minimal Configuration Survival Guide" below, or the "ewok Admin Guide" guide for details.) Installing as apache user or with root access --------------------------------------------- The Short Version ~~~~~~~~~~~~~~~~~ 1. Select ewok install directory (EWOK_HOME) - must NOT be within your web document root (see The Longer Version below for discussion). 2. Then: $ cd /usr/local/src (or somewhere) $ gunzip -c /PATH/TO/ewok-0.XX.tgz | tar xvf - $ cd ewok-0.XX $ make config (then supply ewok home directory, apache config directory, and apache username) $ make $ make install (either as apache user or as root) Now skip to the "Minimal Configuration Survival Guide" below. The Longer Version ~~~~~~~~~~~~~~~~~~ 1. Select ewok install directory (EWOK_HOME). This must NOT be within your web document root directory (e.g. /home/http/htdocs, /var/www/htdocs) etc., or you will seriously compromise the security of your machine. Instead, ewok should be installed OUTSIDE the document root and will be mapped in via an apache alias. A directory at the same level as your htdocs / document root directory is usually a good choice - for example, /home/http/ewok, /var/www/ewok, /opt/web/ewok, etc. 2. Locate your apache configuration directory where the apache httpd.conf file is located ('locate httpd.conf' will work on Linux), as ewok installs its apache configuration files in this directory. Typical locations include /etc/apache, /usr/local/apache/conf, /var/httpd/conf, and /opt/apache/conf. (Alternatively, you can supply EWOK_HOME/conf for this location, but you'll then have to modify the apache httpd.conf to include EWOK_HOME/conf/ewok.conf manually). 3. Decide whether you will install as the apache user or as root. If installing as root, you should provide the apache username when asked so that ewok can make the apache user the owner of the installed files. The apache user is the user named in the 'User' directive in your apache httpd.conf (often 'nobody' or 'http'). 4. Unpack the distribution somewhere temporary (e.g. /usr/local/src), replacing the XX with the version number, and /PATH/TO with the path to wherever you saved the ewok tar file. $ cd /usr/local/src $ gunzip -c /PATH/TO/ewok-0.XX.tgz | tar xvf - $ cd ewok-0.XX 5. Configure and make. If you are missing any prerequisite perl modules the 'make config' will complain, and you should install the missing modules before trying again. $ make config (then supply ewok home directory, apache config directory and apache username) $ make 6. Install, either as the apache user or as root: $ make install Now continue with the "Minimal Configuration Survival Guide" below. Minimal Configuration Survival Guide ------------------------------------ This section is designed to get you up and running with a minimal configuration. For more advanced configuration, see the "ewok Admin Guide":admin/ (also at http://www.openfusion.com.au/ewok/doc/admin/). 1. Prepare an initial staging directory to play with ewok supports a staging / publishing model that lets you use dynamic component-based pages for authoring, and then publish those files to static html for presentation (for performance). We recommend you begin getting familiar with ewok by just setting up an initial staging directory, and come back to publishing later. Staging directories can be located either within your document root or outside it and mapped in using aliases. We suggest you either create a brand new directory: $ mkdir /home/http/foo or copy some existing content to a new tree: $ cp -rp /home/http/htdocs /home/http/foo 2. Edit Config.pm Edit the EWOK_HOME/conf/Config.pm file and update at least the variables in the section marked 'MANDATORY'. You should update at least the following: - @EWOK_STAGE_DIRS - replace the placeholder '/PATH/TO/foo' with the staging directory you created above - @EWOK_TOP_DIRS_ADD - if your staging directory is outside your document root replace the placeholder 'foo' with the alias name you want to use; if it is within your document root comment or delete the 'foo' placeholder - @EWOK_ADMINS - replace the 'johnny_admin jane_admin' placeholders with the usernames you wish to be ewok administrators (superusers) - $EWOK_ADMIN_MAILTO and $EWOK_MAILDOMAIN - update appropriately for your domain 3. Edit ewok.conf Edit the EWOK_HOME/conf/ewok.conf file and change the /PATH/TO/foo placeholders to the full path of your staging directory. If your directory is outside the apache document root you should update the staging Alias directive appropriately (to whatever you used in @EWOK_TOP_DIRS_ADD in Config.pm); if it is within the document root you should comment the Alias directive out. 4. Check or setup authentication You should also review the Authentication Sections in the /ewok and staging directories. If you have no existing authentication mechanisms set up you will need to setup usernames and passwords in the AuthUserFile file. See http://httpd.apache.org/docs/howto/auth.html for an introduction to apache authentication and access control. If you have existing authentication mechanisms in place then simply update the Authentication Sections appropriately, of course. Play! ----- ewok should now be ready to try out. Stop and start your apache, and then go to http://your.domain.com/ewok/ and you should find yourself in the ewok file manager. For an introduction to the file manager and ewok more generally, see "ewok User Guide" at http://your.domain.com/ewok/doc/user/ (or http://www.openfusion.com.au/labs/ewok/doc/user/ for the latest version). For documentation on administering and managing ewok, see "Administering ewok" at http://your.domain.com/ewok/doc/admin/ (or http://www.openfusion.com.au/labs/ewok/doc/admin/ for the latest version).