// -----------------------------------------------------------------------
// This file is part of AROUNDMe
// 
// Copyright (C) 2003-2008 Barnraiser
// http://www.barnraiser.org/
// info@barnraiser.org
// 
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
// 
// This program 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 General Public License for more details.
// 
// You should have received a copy of the GNU General Public License
// along with this program; see the file COPYING.txt.  If not, see
// <http://www.gnu.org/licenses/>
// -----------------------------------------------------------------------


>> AROUNDMe identity server installation guide
   This guide is intended for anyone wishing to install AROUNDMe identity
   server. An understanding of domain name setup, FTP, changing
   directory privileges and web servers is required. Please read the
   terms of the license prior to installation.


>> Overview
   You can create many URL based identities using AROUNDMe identity
   server. Each identity has a unique URL such as http://tom.example.org
   or http://sebastian.example.org . This product should be installed
   under the main domain; in this case http://example.org (not
   http://www.example.org).

   This guide covers a four step installation; uploading AROUNDMe
   identity server, setting up your domain, running the installer and
   finally accessing and testing your installation.


>> Pre installation checks
   AROUNDMe identity server requires a web server running either Apache
   1.3/2.x or IIS5/IIS6 with PHP5.x installed including Curl, BCMath and
   GD library. AROUNDMe identity server additionally requires a MySQL 4.1
   or MySQL 5.0 database.

   The installer does it's best to check for these things and inform you,
   so if in doubt the best strategy is to continue.


>> Extracting and uploading
   Download the latest release of AROUNDMe identity server and unzip/untar
   it onto your local computer. FTP upload ALL the files up a directory on
   your webserver. Write down the path to the index.php file which will be
   something like:

       /public_html/aroundme_i_2008_01_17/aroundme_i/

   The above path will be used for all following examples.


>> Setting up your identity subdomains
   Point your main domain name to the installation path. Each Internet service
   provider has a different way to set up this. Look through your control panel
   and if in doubt contact your Internet service provider support team and ask
   them "How do I point http://example.org to
   /public_html/aroundme_i_2008_01_17/aroundme_i/ "?

   You will only be able to use subdomains if you have full control over your
   webserver. If not, then see 'single subdomain'.

   To do this you must have wildcard domain names pointing to your server. You can
   test this by typing the following domains into your browser:

      http://www.example.org
      http://foo.example.org
      http://example.org

   All of these should go to your webserver. If they do, then you are ready to
   continue to install AROUNDMe identity server. If not, contact your Internet
   service provider support team and request that all sub domains be pointed
   to your webserver.

   Please see 'Appendix A' if you are testing this installation on your local
   computer for testing.


>> Installing AROUNDMe identity server
   Open your browser and type in your main domain URL. You will be presented
   with an installation screen. Follow the instructions on screen. Once complete
   AROUNDMe identity server will be installed and you will be taken to a
   maintainance screen where you can create your own identity.


>> Testing your installation
   Create an identity by clicking 'create account'. Follow the link to your
   OpenID or type the URL directly into a browser. You will see a 'connect'
   button at the top of the page. Press it, enter your OpenID and press 'go'.
   You will now be logged in to your identity account on your installation of
   AROUNDMe identity server. Press disconnect to log out.

   Enter either http://tom.calthrop.info or http://sebastian.oblom.se into
   your browser. You are now looking at either Tom or Sebastians AROUNDMe
   Personal identity installations. Enter your OpenID URL in the OpenID
   field under the connect section of the web page and press 'GO'.

   You will now be taken to your own OpenID and asked for your password.
   Look up at the browser URL and confirm that it displays your OpenID
   URL. If so enter your password.

   Next you will see a screen with some of your identity information.
   Select what information you want to pass to Tom or Sebastians web site.
   Lastly press 'ALLOW'. You will be returned to Tom or Sebastians web
   site and logged in.

   Your installation is fully working. See the Quickstart guide on web
   site for a more information on creating your web site.

   Please note that you can log into your maintainance area at any time by
   typing in http://example.org/maintain.php into a browser.



>> Appendix A – localhost installation
   If you are installing on a localhost then there is a good chance that you are a
   different user that your web server. You therefore need to alter the owner of
   the AROUNDMe identity server files and modify their permissions.

   Establish the owner name of your web server (in this example we use Apache).
   Type 'ps aux' into your command line and look for processes with the name 'apache'.
   You will see the owner; in this case 'www-data':

   Change the owner recursively ( -R) to 'www-data' on the AROUNDMe identity server directory.

   chown -R www-data aroundme_i/

   You may need to be connected as root to do this. If the operating system reports
   that you do not have permissions then repeat the equivalent command as
   root (example for Ubuntu):

   sudo chown -R www-data aroundme_i/

   Next modify the permissions:

   chmod -R 770 aroundme_i/

   The following uses the example webspace name of 'gardening'. The following assumes
   you have access to edit your Apache vhosts file which is typically held in
   /etc/apache2/sites-enabled/ (backup then edit 000-default). Then add the texts
   below. Once complete restart Apache.

   <VirtualHost *:80>
      ServerName gardening.localhost
      DocumentRoot /home/www/aroundme_i/aroundme_i
      DirectoryIndex index.php index.html index.html index.htm index.shtml
   </VirtualHost>

// DOCUMENT ENDS -------------------------------------------------------