I've updated the web/README to make the instructions a bit clearer on setting up a test environment of the AUR. Also, I plan to submit several patches for HTML/template updates over the next couple of weeks so please let me know if this patch format is not correct. Cheers Signed-off-by: Thayer Williams <thayerw@gmail.com> --- web/README | 373 ++++++++++++++++++++++++++++++++++-------------------------- 1 files changed, 210 insertions(+), 163 deletions(-) diff --git a/web/README b/web/README index 041b521..5be144d 100644 --- a/web/README +++ b/web/README @@ -1,191 +1,238 @@ -Setup on Arch Linux: -==================== -1) Install Apache, MySQL, PHP, and git - # pacman -Sy apache mysql php git +AUR Development HOWTO +===================== -2) Set a local 'hostname' of 'aur' - - Edit /etc/hosts and append 'aur' to loopback address - 127.0.0.1 localhost aur +The following instructions will assist in setting up a test environment for AUR +development. These steps assume you are using Arch Linux; if this is not the +case, consult your distribution's documentation for package installation, etc.. -3) Configure Apache +If you require further assistance, please post to the AUR mailing lists: - - Edit /etc/httpd/conf/httpd.conf and enable PHP support - by adding the following lines. + http://mailman.archlinux.org/mailman/listinfo/aur-dev + http://mailman.archlinux.org/mailman/listinfo/aur-general + + +Getting started +--------------- + +AUR development will require the installation of the following: + + # pacman -S apache mysql php php-apache php-pear git + +Refer to the Arch Wiki LAMP article if you'd like some assistance setting up +an http/mysql/php server configuration: + + http://wiki.archlinux.org/index.php/LAMP + + +Configure Apache +---------------- + +Enable PHP support by editing /etc/httpd/conf/httpd.conf and adding the +following lines to the appropriate sections: LoadModule php5_module modules/libphp5.so Include conf/extra/php5_module.conf - - 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 - Order allow,deny - Allow from all - </Directory> - </VirtualHost> - -4) Clone the AUR project (using the MYUSER from above) - $ cd - $ git clone git://projects.archlinux.org/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 - - If those php extensions are separate packages on your system, install - them. - - 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 php.ini: - - include_path = ".:/usr/share/pear" - - PEAR's path may vary depending on your set up. - - - AUR does not work properly with PHP's short open tag enabled. - Be sure you have this in php.ini: - short_open_tag = Off - -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. - # pacman -S words mysql-python - # cd ~/aur/support/schema/ - # python gendummydata.py dummy-data.sql - # bzip2 dummy-data.sql - # bzcat dummy-data.sql.bz2 | mysql -uaur -p AUR - (give password 'aur' at the prompt) - - If your test data consists of real people and real email addresses consider - inserting bogus addressess to avoid sending unwanted spam from testing. You - can insert garbage addresses with: - mysql> UPDATE Users SET Email = RAND() * RAND(); - -7) Copy the config.inc.proto file to config.inc. Modify as needed. - # cd ~/aur/web/lib/ - # cp config.inc.proto 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 +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 + Order allow,deny + Allow from all + </Directory> + </VirtualHost> + + +Configure PHP +------------- + +Make sure you have mysql and json enabled in PHP by editing /etc/php/php.ini +and uncommenting/adding these lines: + + extension=mysql.so + extension=json.so + +AUR requires PEAR (installed above) 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 + +If not already present, put PEAR in your php include_path in php.ini: + + include_path = ".:/usr/share/pear" + +AUR does not work properly with the PHP short_open_tag enabled so make sure +this is disabled in /etc/php/php.ini: + + short_open_tag = Off + + +Configure MySQL +--------------- + +Start the MySQL service: + + # /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 (when prompted use 'aur' as password): + + $ mysql -uaur -p AUR < ~/aur/support/schema/aur-schema.sql + +Optionally load some test data for development purposes: + + # pacman -S words mysql-python fortune-mod + $ cd ~/aur/support/schema/ + $ python gendummydata.py dummy-data.sql + $ bzip2 dummy-data.sql + $ bzcat dummy-data.sql.bz2 | mysql -uaur -p AUR + + (again use 'aur' as password when prompted) + +If your test data consists of real people and real email addresses consider +inserting bogus addressess to avoid sending unwanted spam from testing. You can +insert garbage addresses with: + + $ mysql -uaur -p AUR + mysql> UPDATE Users SET Email = RAND() * RAND(); + + +Set a local hostname of 'aur' +----------------------------- + +Edit /etc/hosts and append 'aur' to loopback address: + + 127.0.0.1 localhost aur + + +Clone the AUR project (using the MYUSER from above): +---------------------------------------------------- + + $ cd + $ git clone git://projects.archlinux.org/aur.git + + +Enable the AUR web config +------------------------- + +Copy the config.inc.proto file to config.inc and modify as needed: + + $ cd ~/aur/web/lib/ + $ cp config.inc.proto config.inc + + +Final Steps +----------- + +Point your web browser to http://aur + +If you encounter any problems (such as 403 Forbidden), refer to the Arch Wiki LAMP +article for tips: http://wiki.archlinux.org/index.php/LAMP + + + +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 +There is also a template to model the site's top pages in template.phps + +Scripts +------- -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. + 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. + 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. + 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). + 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 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). + PHP script to search the package database. It should support searching by + 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: -====================== + 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 + + This 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. + + 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. + + The collection of package build files hosted via the AUR web site. -- 1.6.6.1