Update documentation.

Signed-off-by: Loui Chang <louipc.ist@gmail.com>
Signed-off-by: Callan Barrett <wizzomafizzo@gmail.com>

1 files changed, 169 insertions, 0 deletions

diff --git a/web/README b/web/README
new file mode 100644
index 00000000..b0e6c39f
--- /dev/null
+++ b/web/README
@@ -0,0 +1,169 @@
+Setup on Arch Linux:
+====================
+1) Install Apache, MySQL, PHP, and git 
+  # pacman -Sy apache mysql php git 
+
+2) Set a local 'hostname' of 'aur'
+ - Edit /etc/hosts and append 'aur' to loopback address
+   127.0.0.1    localhost aur
+
+3) Configure Apache
+
+ - Edit /etc/httpd/conf/httpd.conf and make sure that PHP
+   support is enabled by uncommenting the LoadModule line
+   that specifies the PHP module.
+
+ - Also append the following snippet to enable the aur
+   Virtual Host (Replace MYUSER with your username).
+
+   <VirtualHost aur:80>
+   Servername    aur
+   DocumentRoot    /home/MYUSER/aur/web/html
+   ErrorLog    /var/log/httpd/aur-error.log
+   CustomLog   /var/log/httpd/aur-access.log combined
+     <Directory /home/MYUSER/aur/web/html>
+       Options Indexes FollowSymLinks
+       AllowOverride All
+     </Directory>
+   </VirtualHost>
+
+4) Clone the AUR project (using the MYUSER from above)
+   $ cd
+   $ git clone http://projects.archlinux.org/git/aur.git
+
+5) Configure PHP
+   Make sure you have mysql and json enabled in PHP.
+
+ - Edit php.ini and uncomment/add these lines:
+   extension=mysql.so
+   extension=json.so
+
+   AUR requires PEAR and the File_Find module.
+   Installing PEAR will vary depending on the system and may already
+   be included with PHP. You can also find it in the PHP source distribution.
+
+   PHP sources: http://www.php.net/downloads.php
+   File_Find PEAR module: http://pear.php.net/package/File_Find
+   
+ - Install the File_Find PEAR package:
+   # pear install File_Find
+
+ - Put PEAR in your php include_path in web/html/.htaccess:
+
+   php value include_path = ".:../lib:../lang:/usr/share/pear"
+
+   PEAR's path may vary depending on your set up.
+
+6) Configure MySQL
+ - Start the MySQL service. Example:
+   # /etc/rc.d/mysqld start
+
+ - Connect to the mysql client
+   # mysql -uroot
+
+ - Issue the following commands to the mysql client
+   mysql> CREATE DATABASE AUR;
+   mysql> GRANT ALL PRIVILEGES ON AUR.* to aur@localhost
+        > identified by 'aur';
+   mysql> FLUSH PRIVILEGES;
+   mysql> quit
+
+ - Load the schema file
+   # mysql -uaur -p AUR < ~/aur/support/schema/aur-schema.sql
+   (give password 'aur' at the prompt)
+
+ - Optionally load some test data for development purposes.
+   # bzcat ~/aur/support/schema/dummy-data.sql.bz2 | mysql -uaur -p AUR
+   (give password 'aur' at the prompt)
+
+7) Copy the config.inc.proto file to config.inc. Modify as needed.
+   # cd ~/aur/web/lib/
+   # cp config.inc.profo config.inc
+
+8) Point your browser to http://aur
+
+
+Web Interface:
+==============
+
+Directory Layout:
+-----------------
+./html        - DocumentRoot for AUR, where the PHP scripts live.
+./html/css    - CSS stylesheets
+./html/images - Any AUR images live here.
+./lib         - Supporting PHP include files.  Access denied to Apache.
+./template    - Where most of the html markup resides and minimal
+                amount of PHP scripting.
+
+                There is also a template to model the site's top pages in
+                template.phps 
+
+
+Scripts:
+--------
+- lib/aur.inc
+  This is where we can stick functions that can be shared
+  between the various scripts.  Also a good place to put the
+  MySQL authentication variables since it should live outside
+  the DocumentRoot.
+
+- html/login.php (probably index.php)
+  PHP script to handle logging users into the AUR web site.  It
+  authenticates using the email address and a password against
+  the Users table.  Once authenticated, a session id is generated
+  and stored in the Sessions table and sent as a cookie to the
+  user's browser.
+
+- html/logout.php
+  PHP script to logout.  It clears the session id from the
+  Sessions table and unsets the cookie.
+
+- html/account.php
+  PHP script to handle registering for a new account.  It prompts
+  the visitor for account information: Email, password, real name,
+  irc nick.  The info is recorded in the Users table.  Perhaps later,
+  we can add a preferences field that allows the user to request to
+  be notified when new packages are submitted so that they can cast
+  votes for them?
+
+  If a TU is logged into the system, they can edit accounts and set
+  the account type (regular user or TU).  If a Dev is logged in, they
+  can also set the account type to Dev.  TUs and Devs are able to
+  delete accounts.  If an account is deleted, all "Unsupported"
+  packages are orphaned (the MaintainerUID field in the Packages
+  table is set to Null).
+
+- html/packages.php
+  PHP script to search the package database.  It should support
+  searching by location ("unsupported", "community", "extra"), name,
+  category, maintainer, popularity, etc.  It should resemble the
+  packages.php script on archlinux.org.  A checkbox should be
+  included next to each package to allow users to flag a package
+  out of date, adopt it, and vote for it (and reverse operations).
+
+- html/pkgsubmit.php
+  This is the PHP script that allows users to upload a new package.
+  The package format will be a tgz containing the PKGBUILD,
+  scriptlets, and patches necessary to build the package from
+  source.  Initially, the user submitting the package can select
+  its category (network, devel, etc) but that can be modified
+  later by the adopting TU.  The script makes appropriate entries
+  into the database (and perhaps notifies interested users of the
+  new package).
+
+
+Terms and Definitions:
+======================
+AUR - Arch Linux User-Community Repository
+	Includes:
+	- the AUR web site,
+	- the [unsupported] 'repository'
+	- the [community] repository managed by the TUs
+
+TU - Trusted User
+	A user that can add binary packages to the [community]
+	repository and administer AUR.
+
+[unsupported]
+	The collection of package build files hosted via the AUR web site.
+